ORGONAUT
Login Signup
Docs
Agents and API
Connect MCP clients

Connect MCP clients

Orgonaut exposes one canonical remote MCP server:

  • /mcp/orgonaut

Remote MCP access is available on the business, enterprise, and agency plans. free and team tenants can still use the REST API token surface according to their plan, but the MCP OAuth metadata, MCP transport, and connected-app management UI stay unavailable until the tenant upgrades.

This server is read-first in V1. It is designed for organisational review, scenario review, analytical assistant workflows, and governed scenario action planning and confirmation. It does not support baseline writes, scenario promotion, snapshot restore, generic CRUD outside the approved scenario surface, or tenant admin/integration/import mutations.

The full tool, resource, and prompt catalog lives in the MCP reference. This page is intentionally focused on transport and authentication so the catalog only needs to be maintained in one place.

Preferred setup: tenant-hosted OAuth

Use the tenant host as the MCP resource URL, for example:

  • https://acme.orgonaut.co/mcp/orgonaut

Orgonaut publishes the OAuth metadata and dynamic client registration endpoints that remote MCP clients expect:

  • https://acme.orgonaut.co/.well-known/oauth-protected-resource/mcp/orgonaut
  • https://acme.orgonaut.co/.well-known/oauth-authorization-server/mcp/orgonaut
  • https://acme.orgonaut.co/oauth/register
  • https://acme.orgonaut.co/oauth/authorize
  • https://acme.orgonaut.co/oauth/token

OAuth clients should connect to the tenant-host MCP URL directly. Tenant scope is derived from the tenant host plus the bound MCP resource, so X-Tenant is not required for the OAuth path.

Dynamic client registration is open by default in V1. If you need to restrict redirect URIs, set MCP_REDIRECT_DOMAINS explicitly; otherwise Orgonaut allows the remote MCP client's own redirect URI during registration.

The canonical OAuth transport scope is:

  • mcp:use

For mainstream remote MCP clients such as ChatGPT, mcp:use is the only scope that should normally be requested during OAuth setup. Orgonaut still enforces the signed-in user's tenant role and domain permissions inside every tool and resource handler.

Some remote MCP clients only surface tools in their UI. When that happens, use capability.list, capability.explain, org.review.guide, and scenario.review.guide to reach the broader catalog without relying on resource or prompt UI support.

For governed action tools, Orgonaut also enforces ai.scenarios.draft plus the same underlying domain permissions used by the in-product scenario workflows. Planning a change does not execute it immediately: clients must still call scenario.action.confirm with the returned proposal_id.

Advanced clients can also request the normal Orgonaut tenant abilities they need, such as scenarios.read, org-units.read, costs.read, org-metrics.read, teams.read, and placements.read. When present, those extra scopes act as an explicit narrowing layer on top of the user's normal tenant access.

Manual fallback: bearer token plus X-Tenant

For manual clients or compatibility testing, Orgonaut still accepts tenant-scoped bearer tokens.

Create a token in:

  • Settings → API and MCP on plans that include MCP
  • Settings → API tokens on plans that only expose REST API tokens

Grant:

  • mcp.access or legacy mcp to open the MCP transport
  • the normal read abilities for the surfaces you want to query

Send these headers on every MCP request:

  • Authorization: Bearer <token>
  • X-Tenant: <tenant-slug>

This fallback exists for clients that do not support the OAuth flow yet. The tenant-hosted OAuth path is the preferred setup, and the transport still requires an MCP-enabled plan.

Scope rules

  • Baseline is represented by scenario_id = null
  • Scenario-aware tools verify that the requested scenario belongs to the active tenant
  • Scenario action tools require a mutable scenario_id and never create direct baseline writes
  • MCP handlers do not infer tenant scope from tool arguments
  • OAuth clients are tenant-scoped by tenant host plus bound resource
  • Manual bearer-token clients are tenant-scoped by token plus X-Tenant

Next step

Once the client can authenticate successfully:

  1. Use MCP reference for the canonical catalog and first-call patterns.
  2. If the client UI only shows tools, start with capability.list and then capability.explain.
  3. Use ChatGPT custom app setup if you are connecting ChatGPT specifically.
  4. Use API reference if your integration needs REST endpoints instead of MCP.