ORGONAUT
Login Signup
Docs
Agents and API
ChatGPT custom app setup (MCP + OAuth)

ChatGPT custom app setup (MCP + OAuth)

Use this guide to connect your ChatGPT account to a custom Orgonaut app over MCP with OAuth.

This run book is written for tenant-hosted Orgonaut environments where each customer has its own subdomain, for example:

  • https://acme.orgonaut.co

For a distributable plugin, shared-host OAuth can use https://app.orgonaut.co/mcp/orgonaut for every MCP-entitled organisation. During consent, select and approve exactly one organisation. The client should discover the shared metadata and use its advertised /oauth/mcp-shared/authorize, /oauth/mcp-shared/token and /oauth/mcp-shared/register URLs. The scope remains mcp:use; send no X-Tenant header. A web organisation or scenario switch does not change this connection. Shared-host support defaults to disabled in new deployments; use the tenant-hosted steps below when it is unavailable. See Connect MCP clients for availability and connection rules.

1) Prerequisites

Before you start, confirm:

  1. You can sign in to your Orgonaut tenant.
  2. You can reach your tenant domain in a browser (HTTPS required).
  3. You have permission to authorize applications for your tenant account.
  4. Your environment exposes the MCP and OAuth endpoints listed below.

If your production base domain differs from orgonaut.co, keep the same paths and replace only the host.

2) Endpoint checklist (copy/paste)

For tenant acme, these are the exact endpoints ChatGPT needs during MCP + OAuth setup:

MCP server URL

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

OAuth protected resource metadata

  • https://acme.orgonaut.co/.well-known/oauth-protected-resource/mcp/orgonaut

OAuth authorization server metadata

  • https://acme.orgonaut.co/.well-known/oauth-authorization-server/mcp/orgonaut

OAuth dynamic client registration

  • https://acme.orgonaut.co/oauth/register

OAuth authorization endpoint

  • https://acme.orgonaut.co/oauth/authorize

OAuth token endpoint

  • https://acme.orgonaut.co/oauth/token

3) Scope planning

For ChatGPT, request only the MCP transport scope:

  • mcp:use

Orgonaut still enforces your signed-in user's tenant role and data permissions on every MCP tool and resource call. ChatGPT does not need the full Orgonaut ability catalog during setup.

Advanced clients may optionally request extra Orgonaut ability scopes, such as:

  • scenarios.read
  • org-units.read
  • teams.read
  • placements.read
  • costs.read
  • org-metrics.read

Those extra scopes act as an explicit narrowing layer for clients that want least-privilege tokens beyond the user's normal tenant access.

4) Create the custom app in ChatGPT

  1. In ChatGPT, open Settings → Connectors / Custom integrations (wording may vary by plan).
  2. Choose to add a new MCP-compatible custom app.
  3. Set the server URL to:
    • https://acme.orgonaut.co/mcp/orgonaut
  4. Choose OAuth 2.0 as the auth method.
  5. If prompted for manual OAuth values, use:
    • Authorization URL: https://acme.orgonaut.co/oauth/authorize
    • Token URL: https://acme.orgonaut.co/oauth/token
    • Registration URL: https://acme.orgonaut.co/oauth/register
  6. Requested scopes:
    • mcp:use
  7. Save and continue.

ChatGPT should then read the well-known metadata and begin the authorization flow against your tenant-hosted endpoints.

Orgonaut's dynamic client registration endpoint is JSON-only and accepts ChatGPT's redirect URI by default in V1. If you later restrict MCP_REDIRECT_DOMAINS, make sure ChatGPT's redirect host is still allowed.

  1. ChatGPT redirects you to your Orgonaut tenant authorization page:
    • https://acme.orgonaut.co/oauth/authorize
  2. Sign in (if required).
  3. Review the compact authorization screen showing the app, organisation, account, and redirect target.
  4. Approve consent.
  5. You are redirected back to ChatGPT, which exchanges the code at:
    • https://acme.orgonaut.co/oauth/token

Once complete, ChatGPT has a tenant-scoped token for MCP calls.

6) Validate the connection in ChatGPT

Run these quick prompts in ChatGPT against your Orgonaut app:

  1. “List available scenarios.”
  2. “Give me an org summary for baseline.”
  3. “Show org unit metrics for engineering.”
  4. “Create a scenario called Test restructure and move one person to another team in it.” ChatGPT should show you the proposed change and wait for your approval before applying it. Live is not changed.

Under the hood, ChatGPT should be able to call MCP tools such as:

  • scenario.list
  • org.summary
  • org.unit.metrics
  • scenario.history
  • tenant.settings
  • scenario.create, scenario.change.preview and scenario.action.confirm
  • scenario.import.preview and scenario.import.confirm, to load an OrgSpec document into a planning scenario after you approve it

For the full canonical tool, resource, and prompt catalog, use MCP reference.

7) Troubleshooting run book

A) “Authorization failed” during connect

Check:

  • Tenant host is correct (acme.orgonaut.co, not the docs host).
  • OAuth endpoints are reachable:
    • https://acme.orgonaut.co/oauth/authorize
    • https://acme.orgonaut.co/oauth/token
    • https://acme.orgonaut.co/oauth/register
  • Well-known metadata resolves:
    • https://acme.orgonaut.co/.well-known/oauth-protected-resource/mcp/orgonaut
    • https://acme.orgonaut.co/.well-known/oauth-authorization-server/mcp/orgonaut

B) Connected, but no data returned

Check:

  • Granted scopes include mcp:use.
  • Your signed-in user has tenant data access permissions.
  • You are connecting to the correct tenant subdomain.

C) MCP works for one tenant, not another

Remember: OAuth access is tenant-scoped by host + MCP resource URL. Reconnect using that tenant's own subdomain.

D) New Orgonaut tools are missing

ChatGPT saves the app's tool list when you first connect it. When Orgonaut adds tools, such as scenario.create or scenario.import.preview, open the app in ChatGPT's settings and choose Refresh to load them. If your ChatGPT version has no refresh option, disconnect the app and connect it again.

E) Changes are refused

  • A connection approved as Read only cannot create scenarios, prepare changes or import. Disconnect and connect again with Full access.
  • Creating a scenario needs permission to create scenarios, and importing needs permission to manage imports, in your Orgonaut role.
  • Changes and imports only apply to planning scenarios. Live is never changed over MCP.

8) Security notes

  • Prefer OAuth over manual bearer token setup.
  • Keep scopes least-privileged. For ChatGPT that normally means only mcp:use.
  • Revoke app access in your account if a workspace no longer needs integration.
  • Rotate credentials and re-authorize if you suspect token compromise.

9) Manual fallback (non-OAuth clients)

For clients that do not support OAuth yet, use:

  • MCP URL: https://acme.orgonaut.co/mcp/orgonaut
  • Header: Authorization: Bearer <token>
  • Header: X-Tenant: acme

Token requirements:

  • mcp.access (or legacy mcp) for transport access
  • any required read abilities (scenarios.read, org-units.read, etc.)

This manual MCP path is available on every plan.