How to Authenticate the CrossTrade MCP Server
CrossTrade MCP uses OAuth 2.1 with PKCE and dynamic client registration. From the user's point of view, the entire handshake is one consent screen and one click. This tutorial covers what the client is doing under the hood, how to pick the right scope, and how to revoke when you are done.
What OAuth does in CrossTrade MCP
OAuth is the standard that lets an AI client request access to your CrossTrade account without you pasting a long-lived token into a chat window. The user signs in to CrossTrade once and clicks Allow. The client gets an access token bound to a single scope. The user can revoke at any time.
CrossTrade implements:
- OAuth 2.1 authorization code flow with PKCE
- Dynamic client registration per RFC 7591 (so clients like Claude Code self-register)
- Refresh tokens for long-lived clients
- Revocation per RFC 7009
- Two scopes:
mcp:readandmcp:trade - Discovery via
/.well-known/oauth-protected-resource(RFC 9728) and/.well-known/oauth-authorization-server(RFC 8414)
What dynamic client registration means for normal users
Most MCP clients do not require you to register a developer app first. They register themselves on the fly the first time you connect. You will not see this step; the client handles it. Your only action is approving the consent screen.
The MCP server URL
https://app.crosstrade.io/v1/api/mcp
That is the only URL most clients need. Everything else is discovered automatically.
Prerequisites
| Requirement | Detail |
|---|---|
| CrossTrade subscription | Elite |
| CrossTrade Add-On | v1.13.0 or higher |
| NinjaTrader 8 | Running |
| MCP client | A client that supports remote MCP |
| Browser | Required once for OAuth consent |
Step 1: Add the server URL in the client
The exact field varies by client. Common labels: "MCP server URL", "Add MCP server", "Remote MCP connector". Paste the server URL exactly as shown above.
For specific client steps:
Step 2: The browser opens the consent flow
On the first tool call (or first connection check, depending on the client), CrossTrade returns a 401 with a WWW-Authenticate: Bearer resource_metadata=... header. The client follows the link, discovers the authorization server, registers itself, and opens a browser tab to the CrossTrade consent screen.
You will see:
- The client's display name (what the client told CrossTrade about itself)
- The CrossTrade account being authorized
- The scope requested
If the browser is signed in to a different CrossTrade account than the one you intended, sign out of CrossTrade in that browser tab and retry.
Step 3: Choose or review permissions
The two scopes:
| Scope | Allows | Recommended for |
|---|---|---|
mcp:read | Inspection only: accounts, positions, orders, executions, journal, webhooks, add-on activity, watermarks, market data, NinjaScript source files, backtest results from prior jobs | First run, journal review, webhook audit, copier diagnostics |
mcp:trade | Everything in read, plus: place/modify/cancel orders, flatten/reverse, compile NinjaScript, write NinjaScript files, run new backtests, deploy/stop strategies, emit alerts | Compile loop, backtest jobs, order placement with confirmation, strategy deployment |
Pick the smallest scope that works. Default to mcp:read. You can revoke and re-consent at a higher scope later.
Step 4: Complete authorization
Click Allow. The browser redirects back to the client with an authorization code. The client exchanges the code for an access token at the token endpoint. The token is stored in the client's keychain.
Step 5: Verify connection
In the client, run:
Use read-only tools only. Confirm that CrossTrade MCP is connected, confirm
whether NinjaTrader 8 is connected through the CrossTrade add-on, list my
available accounts, and summarize any open positions or working orders.
Do not place, cancel, modify, flatten, deploy, or write anything.
You should see a response with accounts and connection state. If you see a 401 or 403, see the troubleshooting section.
Step 6: Revoke access when done
To revoke an authorized client:
- Open the CrossTrade AI Clients page.
- Find the client.
- Click Revoke.
Revocation is immediate. Any future tool call returns 401.
Revoke when:
- A client device is lost.
- You no longer use that AI client.
- A token may have been exposed (terminal screenshot, log line, copied-and-pasted to a teammate).
- You want to downgrade an agent from
mcp:tradetomcp:read. Revoke, then reauthorize at the new scope.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 unauthorized | Token expired, never issued, or revoked | Reauthorize from AI Clients |
| 403 Elite required | Account below Elite | Upgrade |
403 insufficient_scope | Tool needs mcp:trade but token has mcp:read | Reauthorize at mcp:trade if the workflow legitimately needs writes |
| OAuth opens but redirect fails | Browser blocked the redirect or popup | Retry from the same browser, allow popups, or try a different browser |
| Consent shows the wrong CrossTrade account | Browser signed in to a different account | Sign out, retry |
| Stale grant after revoke | Client cached the token | Restart the client |
Security checklist
- Treat MCP tokens as account credentials.
- Never paste tokens into log lines, support tickets, or chat threads.
- Revoke after a known exposure.
- Reauthorize for scope downgrades.
- Audit the AI Clients page periodically.
FAQ
Do I need to register a developer app?
No. Most clients use dynamic client registration. CrossTrade hands the client a client_id on the fly.
Can I limit the scope to a specific account?
OAuth scope is per token, not per account. Account-level restrictions live in your prompt and in firm-specific rules.
Are MCP tokens the same as REST API tokens?
No. MCP OAuth tokens carry mcp:* scopes. REST and WebSocket use separate personal access tokens. They are not interchangeable.
Related
- Docs: MCP Authentication
- Docs: MCP Scopes
- Docs: ChatGPT and CrossTrade MCP Authentication
- Learn: Use mcp:read vs mcp:trade
- Learn: Revoke AI Client Access
- Learn: Troubleshoot 401, 403, and 408 Errors