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 every plan, including trials. Organisations saved from a guest draft in an AI assistant can connect straight away. Shared-host metadata, when enabled, is public and does not grant access to an organisation.

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 can create planning scenarios, stage exact changes for confirmation, and import an OrgSpec document into a planning scenario after a preview. It does not support baseline writes, imports into Live, scenario promotion, snapshot restore, generic CRUD outside the approved scenario surface, or tenant admin/integration 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.

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. An mcp:use connection can never see more than the member's role allows: for example, if a role has no costs.read, cost and pay fields stay hidden however the client connects.

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 or previewing a change does not execute it immediately: clients must still call scenario.action.confirm with the returned proposal_id. scenario.create also needs scenarios.create, and scenario.import.preview and scenario.import.confirm need imports.manage.

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.

Shared-host OAuth and distributable plugins

Shared-host connections are available to every MCP-entitled organisation. A distributable plugin uses one server URL for all organisations:

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

The client discovers the matching well-known metadata on app.orgonaut.co. Registration, consent, token exchange and revocation use the advertised /oauth/mcp-shared/ endpoints. Request mcp:use and use the client's S256 PKCE OAuth flow. Send the approved bearer token without an X-Tenant header.

Sign in, select an eligible organisation and explicitly approve the connection. Choose an access level before approving. Full access can read the organisation, create planning scenarios, and prepare scenario changes and imports that you confirm before they apply. Nothing over MCP changes Live. Read only can read the organisation but cannot create scenarios, prepare or apply any change, or import; those tools refuse it. To change the level, disconnect and connect again. The sign-in and consent pages use the same focused authentication layout as Orgonaut CLI connections. After approval, return to your MCP client; it handles the final connection confirmation. The consent screen names the organisation even if you have only one available. Each connection authorises exactly one organisation. Switching organisations or scenarios in the web app does not change that connection. To connect another organisation, start another connection or deliberately reconnect; your client's support for multiple accounts may vary.

The production shared host is available to eligible organisations without a tenant rollout flag. Deployments can disable new connections operationally; use tenant-hosted OAuth if your deployment has disabled the shared transport. Existing tenant-hosted and manual connections continue to work. The same plan, active membership, role and optional scope restrictions apply to shared access. You can disconnect an authorised app through the existing connected-app settings.

Model an organisation before signup

The Orgonaut plugin also supports temporary guest modelling at https://app.orgonaut.co/mcp/orgonaut-agent. Describe your organisation in plain language or paste org data. You do not need to write OrgSpec or sign up first. The agent turns your description into a partial structured model, asks one useful question at a time, and can analyse represented staffing, hierarchy and explicit reporting lines or compare a hypothetical scenario. Approximate counts remain estimates; missing people, email addresses, costs and performance are not invented.

Guest drafts expire after 7 days by default. When you choose to save, the plugin returns a claim link valid for 30 minutes by default. It opens Your organisation is ready on Orgonaut. Use a supported sign-in provider or email and password, complete email verification if required, and continue directly to your model. Your teams, people and scenarios are retained; scenario comparison sources are preserved as read-only snapshots. Repeated links or retries by the same account open the same saved organisation. Another account cannot claim it again. The claim, email verification and saved-model confirmation pages use the matching Orgonaut authentication styling. A saved-model confirmation lets you safely close the page or open your organisation; saving a model does not itself connect ChatGPT's account tools. Connect with OAuth when you want to use those tools.

Declining signup keeps guest modelling available without repeated signup prompts. An expired link can be replaced while its guest draft still exists. An expired draft cannot be recovered through that link; opening it never creates a blank organisation. Protect claim links and do not share your private guest capability. See Security and Data for retention and privacy. Saving uses Orgonaut's existing account/trial flow and asks for no payment details.

Connect your existing organisation through the plugin

The mixed agent endpoint includes the existing account tools alongside its guest tools. Account tools request OAuth when needed; connect, select an MCP-entitled organisation and consent on Orgonaut. They retain the same plan, role, domain and optional token-scope restrictions. Connected users review their selected account without a guest draft or signup invitation. A saved guest model does not grant paid account MCP access.

The original https://app.orgonaut.co/mcp/orgonaut and tenant-hosted endpoints remain supported. Each URL is a separate OAuth audience: after updating a plugin from the original URL to /mcp/orgonaut-agent, deliberately reconnect once. Old tokens cannot be used on the new audience, and switching your web organisation or scenario still does not retarget either account connection.

Before reviewing account data, discover the live tool catalog and run a permitted read such as scenario.list. Check the organisation and scenario in the response. Scenario changes require a proposal preview and explicit confirmation. Do not paste tokens or passwords into chat to fix an OAuth error; reconnect through the client or consult this guide's original endpoint setup.

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.

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.

Scope rules

  • The Live 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 write directly to the Live Baseline
  • MCP handlers do not infer tenant scope from tool arguments
  • OAuth clients are tenant-scoped by tenant host plus bound resource
  • Shared-host OAuth clients are scoped by the organisation approved during consent and the stored shared resource binding
  • 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.

Test the plugin in production

  1. Install or update the Orgonaut plugin, then connect its MCP server at https://app.orgonaut.co/mcp/orgonaut. Complete OAuth sign-in, select an eligible organisation and approve the named connection.
  2. Ask: “List my scenarios, actors and teams.” Check the returned organisation and use actor.list pagination. Verify a known record with actor.profile.
  3. Ask: “List business capabilities, AI solutions and transformation cases.” Open a returned record. Your plan and domain permissions may restrict these reads; missing costs or workforce information must stay hidden.
  4. Ask: “Compare [test scenario] with its source and show its staffing, cost and timeline changes.” Confirm the same scenario is used throughout.
  5. In a disposable planning scenario containing fictional data, ask for a small staffing change. Review the proposal first; only approve it when the target and affected records are correct. Verify the change with a read tool. Live Baseline changes must be refused. Remove the test scenario through the web app when finished.
  6. Switch organisations in the web app and repeat a read. The plugin must remain bound to the organisation named in its OAuth consent. Reconnect deliberately to test a different organisation.
  7. Disconnect the app from Orgonaut's connected-app settings and confirm that subsequent calls require authentication again. Reconnect to resume use.

A saved plugin release and successful public discovery checks do not prove an interactive OAuth connection. Complete the steps above in your actual client.