MCP Servers in Claude Code: Connecting and Configuring

MCP is how you give the agent tools it does not have out of the box. Out of the box it works with files and runs commands; everything else - databases, trackers, external services - arrives through servers.

Why an agent needs MCP

The problem is simple: the agent answers from what it can see. If the data lives outside the repository, it does not know about it and starts guessing.

The cases where a server earns its place:

• A database. The agent sees the real schema rather than your paraphrase, and writes queries against it.
• An issue tracker. It can read the ticket instead of you pasting it into chat.
• An external API. Reaching a service that holds data the task needs.
• Documentation and internal knowledge bases, especially where decisions cannot be derived from the code.

The flip side: every connected server adds tool descriptions to context. Ten servers “just in case” is a measurable cost in every task, including the ones where none of them are needed. Connect what you use. Context spend is covered in limits.

Connecting a server

The order is nearly the same for every server:

1. Work out what kind it is. A local program the agent launches, or a remote service it connects to. That decides the shape of the configuration.
2. Add it to the configuration - a launch command or an address, plus environment variables holding credentials.
3. Put secrets in the environment, not in a config file inside the repository. Exactly the same story as the API key.
4. Choose the scope. A server can be personal, available across all your projects, or project-scoped, in which case the whole team picks it up.
5. Restart the agent. Configuration is read at startup.

A note on project-scoped servers: if the server is described in the repository, everyone who opens the project gets it. That is convenient, and it also means somebody else’s repository can bring along a server configuration you have not read. Look at what you are connecting.

Verifying it is visible

Three checks, in increasing order of reliability:

1. The server list in the interface, which shows status: running, failed, not found.
2. The tool list. Ask the agent which tools it has. A server can be running and still expose nothing if it failed to authenticate.
3. A real call. Ask for something small and safe through that server. Only this confirms the whole chain works.

Common errors

• The server does not start. Usually the launch command is not found: the agent starts it in its own environment rather than your shell, and PATH may differ. Use a full path when in doubt.
• It starts but exposes no tools. Authentication failed. Check the environment variables: an empty variable looks exactly like a missing one.
• Tools exist but the agent ignores them. The descriptions are too vague for it to know when they apply. That is fixed on the server side, in the descriptions.
• Everything works, slowly. The server calls an external system on every invocation. Sometimes exporting the data to a file once is cheaper.
• Name collisions. Two servers expose similarly named tools and the agent picks the wrong one. Disconnect the one you do not need.

Next

On the protocol itself and how to write your own server, see the MCP guide. MCP pairs well with skills: the skill describes the procedure, the server provides the data it needs. The overview is in the Claude Code guide.