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

**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](https://code.claude.com/docs/en/mcp), [Claude Code's network docs](https://code.claude.com/docs/en/network-config), [Cursor's MCP docs](https://cursor.com/docs/mcp) and [Codex's MCP docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), the [MCP transport spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), the [MCP debugging guide](https://modelcontextprotocol.io/docs/tools/debugging) and the [MCP Inspector docs](https://modelcontextprotocol.io/docs/tools/inspector). 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](https://code.claude.com/docs/en/mcp), 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](https://cursor.com/docs/mcp), 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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), 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.

## Step 4: Finish sign-in and use the right credential

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:

1. **Sign-in finished.** Closing the browser tab before you approve leaves the client signed out.
2. **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>`.
3. **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](https://github.com/modelcontextprotocol/inspector) comes from the `modelcontextprotocol` GitHub organisation. It connects to a server without your client:

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

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

```bash
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.

```bash
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](/guides/cursor-mcp-connection-failed/). Every client config is in [MCP install](/docs/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](/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](/docs/mcp-install/) · [MCP tools](/docs/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`.

### Can Cursor and Codex share one config file?

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

## See also

[MCP install](/docs/mcp-install/) · [Cursor MCP connection failed](/guides/cursor-mcp-connection-failed/) · [Install in Claude Code](/install/claude-code/) · [MCP tools](/docs/mcp-tools/) · [Best error tracking MCP servers](/blog/best-error-tracking-mcp-servers/) · [BugTape vs Chrome DevTools MCP](/compare/chrome-devtools-mcp/)

[Start free](https://app.bugtape.ai/console/register?utm_source=bugtape_seo&utm_campaign=mcp-server-not-working). No card needed.

Your team reviews the PR. Agents do not silent-ship.