MCP Servers: How They Work and Why They Break

MCP servers are small programs that give an AI assistant tools it can use: read your analytics, query a database, open a GitHub pull request, check a voice agent's call logs. MCP stands for Model Context Protocol, an open standard Anthropic introduced in late 2024. Any app that speaks it (Claude Code, Claude Desktop, Cursor and a growing list of others) can plug into any server that speaks it, the way any USB device works with any USB port.

If you want a list of servers, directories like mcpservers.org and the official servers repository catalog thousands, and my shortlist of the best MCP servers by job covers the official ones worth connecting. This post is about the part those lists skip: how servers are wired up, and the ways they fail without telling you. We run MCP servers for analytics, our voice agent and Google Search Console in the repository behind this website, and most of what follows is from fixing them.

How an MCP server works

An AI app (the client) connects to a server and asks what it offers. The server answers with:

• Tools: actions the model can call, like "run this analytics query" or "list recent calls".
• Resources: data the model can read, like a file or a record.
• Prompts: reusable instructions the server provides.

The model decides when to call a tool, the client passes the call to the server, and the result comes back into the conversation.

Servers connect in one of two ways. A local server runs on your machine as a process the client starts, talking over standard input and output. A remote server runs on the web and the client talks to it over HTTP. The current spec uses streamable HTTP for remote servers. An older transport based on server-sent events (SSE) is deprecated, and that matters, as one of the failures below shows.

Configuring one

In Claude Code, project servers live in a .mcp.json file at the root of the repository. Ours has four: two local servers started with npx, one local server we built ourselves for the blog, and one remote server. The remote one looks like this:

{
  "mcpServers": {
    "posthog-whitespace": {
      "type": "http",
      "url": "https://mcp.posthog.com/mcp",
      "headers": { "Authorization": "Bearer ${POSTHOG_WHITESPACE_API_KEY}" }
    }
  }
}

The ${VAR} placeholder pulls the key from the environment, so the secret never lands in the file. That design is good. It is also the source of most of the failures below.

The failures we hit, and how to spot them

1. The server loads with zero tools and no error. If the variable in a header is not set at all, the server can register no tools instead of failing. It simply is not there. Current Claude Code versions name the missing variable in claude mcp list and /mcp, so check there first. The other fast diagnosis is to look at the other servers from the same file: if they loaded and this one did not, the problem is the variable, not the server or your approval.

2. A 401 that blames a key that is fine. If the variable exists but is empty, the server receives Authorization: Bearer with nothing after it and rejects it. The error reads like a bad key. Check that the key actually reached the process before you rotate anything.

3. The variable name is almost right. Our settings once held WHITESPACE_POSTHOG_API_KEY while the config read POSTHOG_WHITESPACE_API_KEY. Same words, different order, so nothing was supplied, for weeks. The names must match exactly. We now run a check at the start of every session that flags names the config uses but nothing defines.

4. A redirect that drops your credentials. PostHog's old /sse endpoint now redirects to /mcp. The client follows the redirect but does not carry the Authorization header along, so every call fails with a 401 however good the key is. The fix is to use the current /mcp URL with "type": "http". Passing the token in the URL instead is not a workaround: that endpoint rejects it, and tokens in URLs end up in logs.

5. A config file that is silently ignored. Claude Code also keeps servers in your user settings (~/.claude.json), and a server defined there for a project wins over a server with the same name in the project's .mcp.json. You edit the project file, nothing changes, and nothing warns you. If a server behaves as if your config is being ignored, check the user-level file first, and remove the stale entry with claude mcp remove <name> -s local while Claude Code is closed.

6. A server that answers about the wrong company. We once had an analytics server named just posthog that had authenticated to a different organization's account. It returned confident, plausible numbers about the wrong business. Now every server name says which account it reaches (posthog-whitespace), and servers for other organizations are not configured in this repository at all.

7. A test that lies. Checking for a variable with printenv inside the AI's own shell can report it missing even when the client process has it, because that shell is cleaned of secrets. Check the real process environment, or test the key directly against the service's API.

The cost of having many servers

Every connected server adds its tool descriptions to the model's context. Connect enough servers and a large share of the context is spent on tool definitions before you have asked anything. Clients have started loading tool definitions on demand instead of all at once, which helps, but the advice still holds: connect the servers a project needs, not every server you might want someday.

Running them safely

• Give each server the narrowest key that works. A read-only analytics key is enough for reporting questions.
• Keep secrets out of the config file and out of URLs. Use environment placeholders, and store the values in a secrets manager or a local settings file that is never committed.
• Know what a local server can do. It runs on your machine with your permissions. Install servers from sources you trust, and read what tools they expose before you approve them.
• Name servers for what they reach, so the model, and the person reading its answer, cannot confuse two accounts.

Where to go from here

Start with one server for a system you check every day, like analytics or your CRM, and ask it the questions you normally answer by hand. If it does not show up, work through the failures above in order: most problems are the first three.

If you want MCP servers or AI agents connected to your own systems, that is what our AI integration services and AI agent development cover. For the tools that use these servers to write code, see our AI coding assistant comparison.