MCP Authentication and OAuth

CrossTrade MCP uses OAuth 2.1 with PKCE and dynamic client registration. The transport is Streamable HTTP. Any MCP-compatible client that follows the standard auth discovery flow can connect with just the server URL.

For practical client config, see Setup. For permission boundaries, see Scopes.

Auth model

Element	Value
Authorization framework	OAuth 2.1
PKCE	Required for the authorization code flow
Dynamic client registration	RFC 7591
Resource metadata	RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource
Token type	Bearer
Scopes	mcp:read, mcp:trade
Consent	Browser-based, per scope

The user's CrossTrade account is the identity. Tokens are bound to the user and the scope granted at consent time.

OAuth discovery sequence

A compliant MCP client follows this sequence on the first request:

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 and reads the authorization_servers list.
4. Client GETs /.well-known/oauth-authorization-server on the listed auth server to discover the registration, authorization, and token endpoints.
5. Client POSTs to the registration endpoint and receives 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 signed in) and approves the requested scope.
8. Browser redirects back to the client with an authorization code.
9. Client exchanges the code at the token endpoint, presenting the PKCE verifier.
10. Server returns an access token. Client retries the original request with Authorization: Bearer <token>.

The user only sees the consent screen. Everything else happens between the client and the server.

Dynamic client registration

Most MCP clients self-register on first use. The registration request follows RFC 7591 and includes the client's display name, redirect URI, and the scopes it will request. CrossTrade returns a stable client_id that the client persists for future sessions.

There is no separate developer dashboard step for typical AI clients. If you are building a custom production agent and want to pre-register, contact CrossTrade support.

Consent flow

The consent screen lists:

• The display name your client provided during registration.
• The scope requested: mcp:read or mcp:trade.
• The CrossTrade account being authorized.
• A short summary of what the scope allows.

The user must click Allow to grant. The token is then bound to that scope. Increasing scope later requires a new consent.

Token handling

Property	Behavior
Lifetime	Access tokens expire on a rolling window. Clients should refresh transparently if a refresh token is issued.
Storage	Clients store tokens in their own keychain or secure store. CrossTrade does not see local storage details.
Header	Authorization: Bearer <token>
Revocation	The user can revoke a token from the AI Clients page at any time.
Scope upgrade	Not supported. Re-consent to a new scope rather than upgrading in place.

Personal access tokens

For non-MCP REST and WebSocket use, CrossTrade issues personal access tokens. Those tokens are not interchangeable with MCP OAuth tokens. MCP requires the OAuth flow and the mcp:* scope set.

Revocation

Open app.crosstrade.io/user/my-account?tab=ai-clients to see the connected clients, the scope each one holds, and a revoke button. Revoking immediately invalidates any active session.

Revoke if:

• A client device is lost.
• You no longer use a particular AI client.
• You suspect the token was exposed in logs, terminals, or screenshots.
• You want to downgrade an agent from mcp:trade to mcp:read. Revoke, then reauthorize at the new scope.

Security notes

• Treat MCP tokens as account credentials.
• Never paste tokens into logs, issue trackers, or chat threads.
• If a screenshot or recording captures a token, revoke that token immediately.
• For trade-enabled scope on a funded account, require explicit human confirmation on every order action regardless of what the token allows.
• See Workflows and Safety for guidance on prompt injection and approval gates.

Troubleshooting

Symptom	Likely cause	Fix
401 with invalid_token	Token expired, revoked, or never issued.	Reauthorize.
403 with MCP requires an Elite subscription	The account is below Elite.	Upgrade at Subscriptions.
403 with scope mismatch	Tool requires mcp:trade but the token has mcp:read.	Reauthorize at mcp:trade if the workflow needs write access.
Consent screen shows the wrong CrossTrade account	Browser is signed in to a different account.	Sign out of CrossTrade in that browser tab, then retry.
Token reuse across machines	Tokens are bound to the registered client.	Each device must complete its own OAuth flow.

Related

• Setup
• Scopes
• Capabilities
• Workflows and Safety