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

Symptom	Likely cause	Fix
OAuth opens but shows an Auth0 error	Metadata propagation, Auth0 configuration, wrong resource audience, or a transient authorization-server issue.	Retry with the exact OAuth snippet from Algo Trade Analytics. Confirm CIMD registration and resource-parameter compatibility are enabled.
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 snippet that requests offline_access. Confirm the Authorization Server advertises refresh_token and offline_access.
Callback URL mismatch	The client is using an older fixed-client OAuth path.	Use the Algo Trade Analytics OAuth/CIMD snippet. Do not pre-list local callback URLs.
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. CIMD is already past the registration step.	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 /mcp, choose the Algo Trade Analytics server, select Authenticate, and finish OAuth.
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

1. Call ata_health.
2. Call ata_context.
3. Call ata_mcp_usage_status.
4. List tools from the client.
5. If resources are missing, call ata_list_resources.
6. If a Case Study cannot be found, call ata_list_case_studies.
7. If paid or write tools are blocked, call ata_get_research_contract and read the returned guidance.

Tip

For setup tests, ask the client to list tools and then call only ata_context. Do not start a paid research workflow until the connection, account binding, and scopes are correct.

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