Troubleshoot MCP connections
Professional
Start by confirming the basics:
- the MCP endpoint was copied from the correct Algo Trade Analytics environment,
- the URL is plain text, not a Markdown link,
- the Algo Trade Analytics account has Professional or approved beta MCP entitlement,
- the client completed OAuth in the browser profile signed in to that Algo Trade Analytics account,
- the client requested the scopes needed by the tools it wants to call.
Common Issues
Section titled “Common Issues”| Symptom | Likely cause | Fix |
|---|---|---|
Unknown client: https://claude.ai/… | The claude mcp add command omitted --client-id, so Claude Code presented its own client identity instead of Algo Trade Analytics’s. | Run claude mcp remove algo-trade-analytics, then re-add it with the --client-id value from the Claude Code tab on the MCP Access page. |
Unknown client: https://…client.json | The Algo Trade Analytics CIMD URL has not been imported into the authorization-server tenant. Operator task, not a user task. | Algo Trade Analytics imports the CIMD URL as a third-party application and grants it user-delegated access to the MCP API and required scopes. Contact support if this persists. |
| OAuth opens but shows another Auth0 error | API access policy, login connection, wrong resource audience, or a transient authorization-server issue. | Confirm the CIMD client grant, domain-level login connection, and Resource Parameter Compatibility Profile. Keep the MCP URL as the resource audience. |
OAuth authorization required appears mid-run | The client is using an expired access token and did not receive or use a refresh token. | Reconnect with the OAuth/CIMD setup that requests offline_access. Confirm the Authorization Server advertises refresh_token and allows offline_access. |
| Callback URL mismatch | Codex used an ephemeral callback port, or Auth0 has an older imported CIMD. | Set top-level mcp_oauth_callback_port = 5555, restart Codex, and refresh the imported CIMD application in Auth0. Do not set mcp_oauth_callback_url or add one-off callback entries. |
| macOS repeatedly asks for Codex MCP Credentials | Codex is repeatedly reading MCP OAuth credentials from Keychain, or multiple Codex/helper binaries are touching the same Keychain item. | Set mcp_oauth_credentials_store = "file" in ~/.codex/config.toml, restart Codex, then run codex mcp logout and codex mcp login again. Use Manual API key mode if OAuth remains noisy. |
| Client asks for a bearer token | The client surface does not support remote OAuth, or OAuth mode was not selected. | Use OAuth when available. Otherwise switch to Manual API key and store the token as a secret. |
| Claude Cowork says it cannot add the connector | The setup command was pasted into chat instead of added in connector settings. | Add the remote connector in Claude’s connector/settings UI, then authenticate there. |
| Claude Code shows Needs authentication | The server was registered but OAuth has not been completed. | Run claude mcp login algo-trade-analytics. On builds without that command, run /mcp, choose the Algo Trade Analytics server, select Authenticate, and finish OAuth. |
| Claude Code reports a callback URL mismatch | Claude Code selected a random callback port or an older registration omitted the fixed port. | Run claude mcp remove algo-trade-analytics, re-add it with --callback-port 5555, then run claude mcp login algo-trade-analytics. |
claude mcp login says the port is in use | Another process holds port 5555, or a second Claude Code sign-in is already running. The pinned port serialises sign-ins. | Finish or cancel the other sign-in, free port 5555, then run claude mcp login algo-trade-analytics again. |
| The pasted setup block errors in the terminal | An older snippet contained # lines. Stock zsh does not treat them as comments — it runs them, and punctuation such as (, [, *, <, or an apostrophe then causes a parse error, no matches found, or a hung quote> prompt. | Press Ctrl+C, then copy the commands again from the Claude Code tab on the MCP Access page. The current block contains commands only. |
claude mcp add says the server already exists | A registration under that name is already present in the same scope. claude mcp add never overwrites, so the stale entry survives. | Run both claude mcp remove -s local algo-trade-analytics and claude mcp remove -s user algo-trade-analytics, then re-run the add command. |
| Setup reports success but sign-in still fails | A registration made inside a project folder outranks the shared one. claude mcp add --scope user reports success while the older, --client-id-less local entry keeps being used. | Run claude mcp get algo-trade-analytics. If it reports Scope: Local config, run claude mcp remove -s local algo-trade-analytics from that folder and authenticate again. |
| Wrong browser profile opens | The OS opened a browser profile that is not signed in to the target Algo Trade Analytics account. | Copy the authorization URL into the correct browser profile. |
| Connected but tools are missing | The client has not refreshed its MCP tool list, the account lacks entitlement, or scopes are too narrow. | Reconnect, list tools again, confirm entitlement, and request required scopes. |
mcp:read works but write tools fail | The OAuth grant or manual token lacks write scopes. | Re-authenticate or recreate the token with mcp:research:write, mcp:candidate:write, or mcp:memory:write as needed. |
| Resource skill is missing | The client did not auto-load MCP resources or prompts. | Call ata_read_resource for skill://ata-quant-research-driver/SKILL.md or ata_get_prompt with ata_quant_research_driver. |
| Research call hangs on a heavy check | The task should run through a durable background job. | Use ata_start_research_job, then poll with ata_get_research_job_status. |
| OAuth connection still appears after revoke | The row is retained as revoked audit/status history. | Treat it as inactive. The client must sign in again before it can call MCP. |
| Manual token was copied incorrectly or lost | Algo Trade Analytics only shows the full token once. | Revoke the token and create a new one. |
Debug Checklist
Section titled “Debug Checklist”- Call
ata_health. - Call
ata_context. - Call
ata_mcp_usage_status. - List tools from the client.
- If resources are missing, call
ata_list_resources. - If a Case Study cannot be found, call
ata_list_case_studies. - If paid or write tools are blocked, call
ata_get_research_contractand read the returned guidance.
Related
Section titled “Related” Client Setup Known-good setup snippets for each client type
OAuth and CIMD Auth discovery details and what not to configure manually
Security, Scopes, and Credits Entitlements, revocation, scopes, and credit boundaries