Skip to main content

ChatGPT and CrossTrade MCP Authentication

This page is the canonical technical reference for connecting a ChatGPT-compatible client to CrossTrade MCP. For a screenshot walkthrough, use the ChatGPT setup tutorial.

Supported connection models​

CrossTrade MCP supports any client that implements the Model Context Protocol over Streamable HTTP with OAuth 2.1 and dynamic client registration. The ChatGPT side of that varies by plan and environment.

Connection modelDescription
ChatGPT app / custom connectorA ChatGPT plan that allows registering remote MCP connectors. Add the CrossTrade server URL in the connectors UI.
ChatGPT developer modeAvailable in some plans for tool-use experiments. Add the MCP server URL via the developer settings.
OpenAI API remote MCPUse the OpenAI SDK's remote MCP connector parameter to pass the CrossTrade URL.
API PlaygroundThe OpenAI Playground may support remote MCP for tool-use experiments.

Availability of remote MCP varies by plan and region. If your ChatGPT environment does not list a remote MCP option, the path is not yet enabled for you.

MCP server endpoint​

https://app.crosstrade.io/v1/api/mcp

Transport: Streamable HTTP per the MCP spec.

OAuth discovery sequence​

A compliant client follows this sequence:

  1. Client POSTs to https://app.crosstrade.io/v1/api/mcp without a bearer token.
  2. Server returns 401 Unauthorized with: 
    WWW-Authenticate: Bearer resource_metadata="https://app.crosstrade.io/.well-known/oauth-protected-resource"
  3. Client GETs the resource metadata URL (RFC 9728) and reads the authorization_servers list.
  4. Client GETs /.well-known/oauth-authorization-server (RFC 8414) on the listed authorization server. The response includes:
    • issuer
    • authorization_endpoint
    • token_endpoint
    • registration_endpoint
    • revocation_endpoint
    • response_types_supported: ["code"]
    • grant_types_supported: ["authorization_code", "refresh_token"]
    • code_challenge_methods_supported: ["S256"]
    • token_endpoint_auth_methods_supported: ["none"]
    • scopes_supported: ["mcp:read", "mcp:trade"]
  5. Client POSTs to /v1/oauth/mcp/register (RFC 7591) with client metadata. Server returns a client_id.
  6. Client opens the user's browser to the authorization endpoint with PKCE parameters.
  7. User signs in to CrossTrade (if not already) and approves the requested scope.
  8. Browser redirects back to the client with an authorization code.
  9. Client exchanges the code at /v1/oauth/mcp/token, presenting the PKCE verifier.
  10. Server returns an access token. Client retries the original request with Authorization: Bearer <token>.

Dynamic client registration behavior​

CrossTrade implements RFC 7591. Most ChatGPT-compatible clients self-register on first connect. The user does not need to pre-register a developer app.

Registration is rate-limited per IP (10 registrations per hour). Re-registration is normal for clients that store the client_id locally.

Only public PKCE clients are supported (token_endpoint_auth_method: "none"). There are no client secrets to manage.

The consent screen displays:

  • Client display name (set during registration)
  • Requested scope
  • CrossTrade account being authorized
  • Allow / Deny

The user can only consent to one scope at a time per token. To upgrade from mcp:read to mcp:trade, revoke the existing token and reauthorize at the new scope.

Scope selection​

ScopeAllows
mcp:readInspection-only tools: accounts, connections, positions, orders, executions, journal, webhook history, add-on activity, watermarks, market data, NinjaScript source files, prior backtest results
mcp:tradeAll read tools plus: order placement and management; flatten and reverse; NinjaScript compile and file write; new backtest jobs; strategy deployment and stop; alert emission; workspace and chart writes

mcp:trade is a superset; granting it issues a token with both mcp:read and mcp:trade capability.

Token lifecycle and revocation​

AspectBehavior
Access token lifetimeRolling window; refresh tokens are issued for clients that request them
StorageClient-side keychain or secure store; CrossTrade does not see local storage details
HeaderAuthorization: Bearer <token>
RevocationRFC 7009 at /v1/oauth/mcp/revoke, or via the AI Clients page
Scope upgradeNot supported in place; revoke and reauthorize at the new scope

Common errors​

HTTPerrorCauseResolution
401invalid_tokenToken expired, revoked, or never issuedReauthorize
403subscription_required / MCP requires an Elite subscriptionAccount below EliteUpgrade
403insufficient_scopeTool needs mcp:trade; token has mcp:readReauthorize at mcp:trade
408addon_disconnected / timeoutNT8 closed or add-on disconnectedOpen NT8, verify the add-on
400invalid_grantPKCE mismatch or stale codeRestart the auth flow
429too_many_registrationsRate-limit on /v1/oauth/mcp/registerReuse the existing client_id or retry later

Security notes​

  • Tokens are bound to the registered client. Each device or browser context must complete its own OAuth flow.
  • Never paste tokens into logs, issue trackers, or chat threads.
  • If a token may have been exposed, revoke it immediately.
  • For trade-enabled scope on a funded account, require explicit human confirmation on every order action regardless of what the token allows.
  • For prompt-injection defenses, see MCP Workflows and Safety.