DEV Community

Poorna Reddy
Poorna Reddy

Posted on AI-assisted

Claude Code MCP: Connected but Not Working? Check These Three Gates

#claudecode #claude #ai #mcp

An MCP server can appear in claude mcp list and still fail the first real request. In most cases the connection is fine and one of three separate gates is closed. Checking them in order saves a lot of configuration churn.

The three gates

Every MCP request from Claude Code passes three independent checks:

Gate Question it answers Who controls it
1. Project-server approval May Claude Code load this connection in this project? You, in an interactive session, plus any organisation restrictions
2. Tool permission May Claude call this specific tool now? Claude Code permission rules in personal, project and organisation settings
3. Data access Does the credential behind the server allow this read or write? The external system, for example GitHub, using the token's permissions

Passing one gate says nothing about the next. Approving a tool call in Claude Code cannot grant a repository permission your token lacks, and a token with full access does not help if the project server was never approved.

Read the symptom, then pick the gate

What you see Check first
The server does not appear at all Configuration: project directory, JSON syntax, server name
Approval is pending Gate 1: review the project-server request in an interactive session
Every call asks for permission, or the call is refused Gate 2: the permission rule, written against the actual tool name
Authentication or "not found" errors from the service Gate 3: token expiry, selected repositories, organisation approval

Labels vary by Claude Code version. What matters is which stage failed. Use /mcp inside a session to inspect the connection before you change any files.

One detail catches many people at gate 2. Permission rules can target a whole server or a single tool, and the server sets the tool names. Inspect the real name before writing the rule. A name guessed from your own server label may not match.

Choose the scope before you share anything

Claude Code stores an MCP connection at one of three scopes:

  • Local (the default): you, in the current project.
  • Project: everyone who receives the project's .mcp.json.
  • User: you, across all your projects.

Sharing a Project-scope definition shares the connection, not the access. Each teammate still supplies their own credential, usually through an environment variable referenced in .mcp.json, so the secret never lands in the repository.

Limit access twice

For a read-only task such as summarising an issue, restrict both layers:

  1. Use a read-only endpoint or toolset, so the server only offers read tools.
  2. Use a read-only credential, so the identity cannot write even if someone later swaps the endpoint.

The endpoint limits what the connection exposes. The credential limits what the identity can do. You want both, because either can change without the other.

A quick verification habit

Before trusting a new connection with a larger task, ask for one record you can check by hand: title, state, owner and URL. Open the URL and compare every field. If a field is missing, the answer should say so rather than invent it. Note what you checked and when. That one confirmed lookup becomes your baseline when something breaks later.

Go further

Top comments (0)