Guide

MCP server not working: a checklist for Claude Code, Cursor and Codex

Q: How do I check if an MCP server is working?

Send an initialize request with curl, or connect with the MCP Inspector. A 200 response with serverInfo means the server answers. claude mcp list shows ✔ Connected when Claude Code can reach it.

Q: Can Cursor and Codex share one config file?

No. Cursor reads mcpServers JSON from .cursor/mcp.json. Codex reads [mcp_servers. ] tables from config.toml.

Fix a failing MCP server in Claude Code, Cursor or Codex: status commands, transport, sign-in, tokens, proxies and a manual initialize test.

Short answer: Most MCP failures have one of five causes. The client cannot start a local server, the URL or transport is wrong, sign-in did not finish or has expired, the token is the wrong kind, or the network blocks the request. Ask the client for its status first: claude mcp list in Claude Code, MCP Logs in Cursor's Output panel, codex mcp list in Codex. Then test the server on its own with the MCP Inspector or one curl request. If the server answers on its own, fix the client config.

Page owner: Jaco Veldsman, hi@bugtape.ai. Last checked 2026-10-26. I build BugTape, which runs a hosted MCP server. This checklist works for any MCP server. Sources: Claude Code's MCP docs, Claude Code's network docs, Cursor's MCP docs and Codex's MCP docs, the MCP transport spec, the MCP debugging guide and the MCP Inspector docs. I read all of them on 26 October 2026.

Facts table

Client	Config file	Status check	Sign in again
Claude Code	`~/.claude.json` for local and user scope; `.mcp.json` in the project root for project scope	`claude mcp list`, `claude mcp get <name>`, or `/mcp` in a session	`/mcp`, then the browser steps. Clear authentication in the same menu removes access.
Cursor	`.cursor/mcp.json` in the project; `~/.cursor/mcp.json` for every project	Output panel (Cmd+Shift+U), then MCP Logs	Cursor signs in with OAuth and PKCE, and renews an expired token with the refresh token.
Codex	`~/.codex/config.toml`, or `.codex/config.toml` in a trusted project; one `[mcp_servers.<name>]` table per server	`codex mcp list`, or `/mcp` in the TUI	`codex mcp login <name>`

Cursor uses mcpServers JSON. Codex uses TOML. One config shape does not work in the other client.

Step 1: Read the client's own status

Claude Code (docs, checked 26 Oct 2026). claude mcp list shows a status next to each server, such as ✔ Connected, ! Needs authentication or ✘ Failed to connect. claude mcp get <name> shows one server. A server from a project .mcp.json can show ⏸ Pending approval. Run claude in that folder and approve it. Inside a session, /mcp shows the same status and starts sign-in.

Cursor (docs, checked 26 Oct 2026). Open the Output panel and pick MCP Logs. Cursor's docs say these logs show server start-up, tool calls and error messages. You turn servers on and off under Customize in the sidebar. A disabled server does not load or appear in chat.

Codex (docs, checked 26 Oct 2026). codex mcp list lists the configured servers. In the codex TUI, /mcp shows the active ones. enabled = false in a server's table turns it off without deleting it.

Copy the exact error text before you change anything.

Step 2: Match the transport to the server

MCP has two standard transports. With stdio, the client starts the server as a local process. With Streamable HTTP, the client sends requests to a URL. A config written for one transport fails on the other.

A local server needs a command. In Cursor and Codex that is command and args. In Claude Code it is claude mcp add <name> -- <command> [args...], where -- separates Claude Code's own options from the server command.
A remote server needs a URL. In Cursor and Codex that is url. In Claude Code it is claude mcp add --transport http <name> <url>.
The older SSE transport is deprecated. Claude Code's docs recommend HTTP for remote servers.

Copy the URL from the server's own docs. The MCP endpoint is one exact path, such as https://example.com/mcp. The home page on the same host does not answer MCP requests.

Step 3: Make sure a local server can start

The MCP debugging guide lists these start-up faults:

Working directory. A client can start a server with no useful working directory, such as / on macOS. Use absolute paths in the config.
Environment. A stdio server inherits only part of your environment. Pass API keys with the env setting.
Output. A stdio server must write only MCP messages to stdout. Logs go to stderr. One stray print statement breaks the connection.
Runtime. Run the server's command yourself in a terminal. npx needs Node on the machine where the client runs. Check node --version against the server's README. The MCP Inspector itself needs Node 22.19.0 or newer.
Start-up time. Codex waits 10 seconds by default (startup_timeout_sec). In Claude Code, MCP_TIMEOUT=10000 claude sets a 10-second start-up timeout. A first npx download can take longer than that.

A remote server that uses OAuth needs one completed browser sign-in. In Claude Code, run /mcp and choose the server. In Codex, run codex mcp login <name>. In Cursor, follow its sign-in prompt for that server.

A 401 response means the server received no valid credential. Check three things:

Sign-in finished. Closing the browser tab before you approve leaves the client signed out.
The token is the right kind. Many services issue one key for sending data from an app and another for API or agent access. Use the credential the server's MCP docs name, sent as Authorization: Bearer <token>.
The token reached the client. Codex's bearer_token_env_var names an environment variable. That variable must be set in the shell that starts Codex.

If a token has expired, sign in again. In Claude Code, Clear authentication in /mcp removes the stored sign-in. Removing a remote server with claude mcp remove also deletes its stored OAuth tokens.

Step 5: Check the network

A corporate proxy or TLS inspection can block MCP requests. Claude Code reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY, and trusts extra certificates from NODE_EXTRA_CA_CERTS. Run the curl test below from the same machine. If curl fails too, the network is the cause.

Step 6: Rule out limits

Codex stops a tool call after 60 seconds by default (tool_timeout_sec).
Claude Code warns when a tool returns more than 10,000 tokens and cuts output at 25,000 tokens by default. MAX_MCP_OUTPUT_TOKENS raises the cut-off.
Claude Code has no fixed tool cap per server. Its tool search loads tool definitions only when Claude needs them.

Test a remote server by hand

The MCP Inspector comes from the modelcontextprotocol GitHub organisation. It connects to a server without your client:

npx @modelcontextprotocol/inspector --server-url https://example.com/mcp --transport http

For a quick check in a terminal, send one initialize request:

curl -i -X POST https://example.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0"}}}'

The spec requires both types in Accept. Add -H 'Authorization: Bearer YOUR_TOKEN' if the server needs a token.

Response	What it usually means
`200` with `serverInfo` in the result	The server works. Fix the client config.
`401`	No valid credential. Sign in, or send the right token.
`404` or `405`	Wrong path, or a server that only speaks the old SSE transport.
`406`	The `Accept` header is missing a type.
`400`	The server could not read the request. Check the JSON and the protocol version.
Timeout or connection refused	The server is down, or a proxy or firewall blocks it.

The newer MCP version, 2026-07-28, adds a server/discover request that every server on that version must answer. If a server rejects your version with error -32022, the error data lists the versions it supports.

Testing BugTape's MCP server

BugTape's hosted server is https://app.bugtape.ai/mcp. It uses Streamable HTTP and OAuth. With no credential, it answers 401 with a WWW-Authenticate header that points clients to its sign-in details.

BugTape rejects capture keys (bt_live_ and bt_test_) on MCP. Those keys sit in your app's code and only let the SDK send reports. An agent signs in with OAuth or uses an agent token that starts with bt_pat_.

To prove your client works before you debug anything else, connect the public demo at https://app.bugtape.ai/demo/mcp. It needs no account and no key, and it reads one sample project. The curl request above returns 200 from it.

claude mcp add --transport http bugtape-demo https://app.bugtape.ai/demo/mcp

If the demo connects and your own server does not, the client is fine. For Cursor-specific fixes, read Cursor MCP connection failed. Every client config is in MCP install.

Plans and credits

MCP works on every plan, including Free. On Free and Prepaid credits, each agent read of a bug's captured events costs 2 credits. Free includes 150 credits a month. On Pro ($29 USD a month) those reads are free. A prepaid pack costs $10 USD for 2,000 credits. Detail is on Pricing.

listen (the live wait for the next bug) needs Pro, or prepaid credits on the workspace. On Free without those credits, start with list_recommended_critical. Do not start with list_bugs.

Capture keys (bt_live_ / bt_test_) are rejected for MCP. They only send reports. The agent uses OAuth or a bt_pat_ token. MCP install · MCP tools.

FAQ

Why is my MCP server not working?

The usual causes are a local server that cannot start, a wrong URL or transport, an unfinished or expired sign-in, the wrong kind of token, or a blocked network. The client's status output usually names the cause.

How do I fix an MCP error?

Read the exact error in the client first. Then test the server alone with the MCP Inspector or curl. If it fails alone, fix the server. If it answers alone, fix the client config.

How do I check if an MCP server is working?

Send an initialize request with curl, or connect with the MCP Inspector. A 200 response with serverInfo means the server answers. claude mcp list shows ✔ Connected when Claude Code can reach it.

How do I debug an MCP server?

Start with the MCP Inspector. For a stdio server, write logs to stderr and use absolute paths. For an HTTP server, read the server's own logs and inspect the HTTP responses with curl.

No. Cursor reads mcpServers JSON from .cursor/mcp.json. Codex reads [mcp_servers.<name>] tables from config.toml.