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

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: Use a read-only endpoint or toolset, so the server only offers read tools. 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 The full walkthrough, with a read-only GitHub token, the .mcp.json entry and a troubleshooting table, is on Timo Labs: Claude MCP server integration guide. The architect exam tests these same decisions. See task statement 2.4: MCP server integration in the CCAR-F study guide. To check yourself on exam-style scenarios, try the free Claude Certified Architect practice exam.