# MCP Troubleshooting

> Symptom, cause, and fix tables for CurrencyCore MCP connection, OAuth, organization, plan, quota, config format, and client-specific problems.

Canonical: https://currency-core.com/docs/mcp-troubleshooting/

---
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](/docs/mcp-oauth/) for the consent flow and revocation.
- [MCP tools](/docs/mcp-tools/) for tool inputs and error codes.
- [MCP vs REST](/docs/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](/docs/mcp-claude/). |
| 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.code` and any
  `currencycore/*` metadata.
- The time of the attempt, in UTC.
- The organization you selected.

Then check [status](https://currency-core.com/status/) for an active incident.

## Related

- [MCP OAuth and access](/docs/mcp-oauth/)
- [MCP tools](/docs/mcp-tools/)
- [Errors and retries](/docs/errors/)
- [Billing and limits](/docs/billing/)