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

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 tenant is on the business, enterprise, or agency plan.
  5. 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.”

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

  • scenario.list
  • org.summary
  • org.unit.metrics
  • scenario.history
  • tenant.settings

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.

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 also limited to the business, enterprise, and agency plans.