MCP
MCP Troubleshooting
Symptom, cause, and fix tables for CurrencyCore MCP connection, OAuth, organization, plan, quota, config format, and client-specific problems.
Use this page when a client will not connect, connects but shows the wrong tools, or returns an error on a tool call. Start with the symptom, then apply the fix.
More detail:
- MCP OAuth and access for the consent flow and revocation.
- MCP tools for tool inputs and error codes.
- MCP vs REST if you are not sure MCP is the right path.
Connection
| Symptom | Likely cause | Fix |
|---|---|---|
| The server does not appear in the client’s MCP list | The config file is in the wrong place, the entry is not inside the expected object, or the client was not reloaded | Confirm the file path for your client, save valid JSON, then restart the client or reload the window. |
| The client connects, but every keyed tool fails | The OAuth sign-in was never completed, or the browser flow was closed early | Trigger a tool call again, or use the client’s connect or authenticate action, and finish the browser sign-in. |
| The connection worked yesterday and now fails | The token expired, the organization disabled MCP, or your membership changed | Reconnect. If it still fails, check the MCP switch and your organization membership. |
| The client reports a network or timeout error | The request took longer than the client’s timeout, or a transient API failure occurred | Retry once. Analytics calls over long windows are the slowest. If it repeats, narrow the date range. |
| A browser opens a page that does not finish | The consent page was opened in a different browser profile, or the redirect was blocked | Finish the flow in the same browser where you are signed in to CurrencyCore. Allow the redirect back to the client. |
| The server responds but no tools are listed | The client cached an older tool list, or the connection is unauthenticated | Reconnect and refresh the client’s tool list. In ChatGPT, start a new chat after changing the connector. |
Only two tools and no sign-in prompt
This is a specific pre-fix symptom from the 2026-11-10 audit. It is not caused by your config file.
| Symptom | Cause | Fix |
|---|---|---|
The client lists only list_countries and list_currencies, never opens a browser, and keyed calls are unavailable | This was a server-side issue in older deployments: an unauthenticated MCP initialize returned 200 with only the two public tools and no WWW-Authenticate challenge, and the protected-resource metadata named the bare origin instead of the /mcp URL. The current server returns a 401 challenge and the /mcp resource. | If you still see it, your client may be on a cached connection or an older deployment. Remove and re-add the connector, then retry. If it persists, report the client name, server URL and time of the attempt. Do not start by editing your JSON. |
The two reference tools are unmetered, but the current server requires an
authorized connection for every /mcp request. Seeing them is normal only
after sign-in. Seeing only them, with no sign-in attempt and no keyed tools,
means the client is on an older deployment or a cached tool list.
Authentication
| Symptom | Likely cause | Fix |
|---|---|---|
401 unauthorized | Missing, expired, or invalid token; the client grant was revoked; or your organization membership was removed | Reconnect and sign in. Then confirm you still belong to the organization you selected. |
Sign-in succeeds, but the next call returns 401 | The client did not persist the token, or it is using a different profile or workspace | Remove and re-add the server in that profile. In Cursor, check whether a cloud agent is running in a separate environment. |
| Sign-in loops back to the consent page | The browser session is signed into a different CurrencyCore account, or cookies are blocked | Sign out, sign in with the intended account, and allow cookies for the app and auth domains. |
403 after a successful sign-in | This is usually not authentication. It can be a plan gate, a disabled MCP switch, or an out-of-window history date. | Read the message and see the plan and organization tables below. If the text only says to reconnect, check error.code in the structured tool result. |
| You cannot find an API key to paste | Remote MCP uses OAuth and does not issue an MCP API key | Add the URL and complete the browser sign-in. Do not put a REST key in the MCP config. |
Organization selection
| Symptom | Likely cause | Fix |
|---|---|---|
| The organization picker is empty | Your account belongs to no organization | Create an organization in the dashboard, or ask an owner to invite you. |
| Calls are billed to the wrong organization | The connection is bound to the organization chosen at consent | Disconnect, reconnect, and choose the correct organization. |
| A teammate sees different usage | Grants are per user and per client application | Each person signs in and selects their own organization. Usage belongs to the organization, not the client. |
| Access stops after a team change | Membership is revalidated on every request | Ask an owner to confirm you are still a member. Reconnect after the membership is restored. |
Plan and feature gates
| Symptom | Likely cause | Fix |
|---|---|---|
403 forbidden on analyze_* tools | Analytics require Growth or higher | Upgrade the organization, or use convert, get_rates, get_history, and get_ppp_factor on Free and Starter. |
403 forbidden on get_history for older dates | Free history is limited to the last 30 days | Request a recent window, or upgrade to Starter or higher for full history. |
403 on every keyed tool | MCP is disabled for the organization | Turn the MCP switch back on in Dashboard, Developer, MCP server. |
403 mentions live keys | MCP is exempt from the live-key requirement, so this usually comes from a REST call, not MCP | Check whether the tool is actually calling REST with a key. MCP runs on every plan. |
| A tool is missing from the list | The client has not refreshed its tool list, or it hides tools it cannot authorize | Reconnect and refresh. The analytics tools stay listed even on Free; they fail at call time with 403. |
Quota and rate limits
| Symptom | Likely cause | Fix |
|---|---|---|
429 with “Monthly quota … exceeded” | The organization used its monthly request quota | Wait for the next billing period, upgrade, or raise the hard cap if one is configured. |
429 with “Rate limit exceeded” | The organization hit its per-minute limit | Wait for the window to reset. The tool result includes currencycore/retry_after_s. |
429 returns quickly, even though the first call worked | The MCP server retries transient failures, then surfaces the limit. A long Retry-After is capped at 5 seconds for the retry, so the client still sees a 429. | Back off in the client. Do not loop the tool call. |
| Usage is higher than expected | Each successful keyed tool call is one API request, and an agent may call several tools for one answer | Check the MCP panel in the dashboard. Ask the agent to use fewer tools or a single analytics call. |
| You expected AI credits to be used | MCP does not use AI credits | MCP calls count as API requests. AI credits apply only to the HTTP /v1/ai endpoint. |
Config format
The most common setup failure is using another client’s key name. These are not interchangeable.
| Client | File | Container | URL field |
|---|---|---|---|
| Claude Desktop (legacy JSON) | claude_desktop_config.json | mcpServers | url |
| Claude Code | .mcp.json | mcpServers | url, with type: "http" |
| Cursor | .cursor/mcp.json or ~/.cursor/mcp.json | mcpServers | url |
| VS Code portable | .mcp.json | mcpServers | url, with type: "http" |
| VS Code legacy | .vscode/mcp.json | servers | url, with type: "http" |
| Windsurf / Devin | ~/.config/devin/mcp_config.json | mcpServers | serverUrl |
| Gemini CLI | ~/.gemini/settings.json | mcpServers | httpUrl |
| Codex | config.toml | [mcp_servers.<name>] | url |
| OpenCode V2 | OpenCode config | mcp.servers | url, with type: "remote" |
Other format problems:
| Symptom | Cause | Fix |
|---|---|---|
| The whole file fails to load | Comments or trailing commas in a .json file | Remove them and validate the file as JSON. |
servers is ignored in VS Code | You are using the portable .mcp.json format, which expects mcpServers | Use mcpServers for .mcp.json, and servers only for the legacy .vscode/mcp.json. |
| Cursor cannot see a server | The file is in a different project directory than the one Cursor opened | Put .cursor/mcp.json in the opened project root, or use the global file. |
serverUrl is ignored | You are editing a client that expects url | Check the table above. Cursor, Claude, and VS Code use url. |
httpUrl is ignored | You are editing a client that expects url | httpUrl is the Gemini CLI field. |
Client-specific issues
| Client | Symptom | Fix |
|---|---|---|
| Claude | You cannot find a JSON file for connectors | Remote connectors are added in Settings, then Connectors, then Add custom connector. The JSON file is for local servers. See Claude setup. |
| Claude | The connector was added but Claude does not call it | Ask explicitly: “Use the CurrencyCore convert tool.” Confirm the connector is enabled for the conversation. |
| ChatGPT | The custom MCP option is missing | Full MCP requires a Business, Enterprise, or Edu workspace on the web. Pro accounts have limited read/fetch support. A workspace admin may need to allow the connector. |
| ChatGPT | The tool list is stale after a server change | ChatGPT freezes the tool list until the connector is refreshed. Start a new chat or refresh the connector. |
| Cursor | Tools do not appear after editing JSON | Open Customize, then MCP, and confirm the server is listed. Reload the window. Check the MCP log in the Output panel. |
| Cursor | A cloud agent cannot use the server | Cloud agents run in a separate environment and do not reuse your local OAuth session. Authenticate in that environment separately. |
| VS Code | The server appears but tools are unavailable | Open the Command Palette and run MCP: List Servers, then start the server. Use MCP: Show Output for errors. |
| Gemini CLI | Sign-in fails in a remote shell | gemini mcp auth needs a local browser. Run it on a machine with a browser, or forward the callback to your local browser. |
| Codex | The server is added but unauthenticated | Run the client’s MCP authentication step, or remove and re-add the server with codex mcp add, then retry. |
| OpenCode | The server is not listed | Check the mcp.servers entry in the OpenCode config, then use the client’s MCP authentication flow. |
| Windsurf / Devin | The server is blocked in a company workspace | An enterprise admin may need to allow the server URL in the workspace policy. |
Still stuck
Collect these before asking for help:
- The client name and version.
- The exact config file or UI path you used.
- The tool name and the full error body, including
error.codeand anycurrencycore/*metadata. - The time of the attempt, in UTC.
- The organization you selected.
Then check status for an active incident.