Configuring an MCP Server: Config, Variables, Debugging

Most MCP trouble is configuration rather than protocol. Here is how it is structured and how to debug it.

Config structure

The configuration describes servers: name, how to launch, and environment. Two things are required at minimum.

A server name. Arbitrary, but it ends up in the tool names the agent sees. Short and meaningful beats long: two servers with similar names are a ready-made source of wrong tool choices.

How to launch. For a local server, a command and its arguments. For a remote one, an address. The process environment is specified here too.

There are usually two levels: a user level applying across projects and a project level living in the repository. Choosing between them is covered in connecting.

A practical detail that saves hours: broken JSON often raises no error. The client reads the file, cannot parse it, and behaves as though no servers exist. If nothing changed after an edit, check the syntax first.

Environment variables and secrets

One rule: tokens live in the environment and the config references them.

Why this matters more than it looks:

• A project config lives in the repository. A token in it reaches everyone who clones.
• Deleting the file later is not enough: the token stays in git history and must be revoked.
• The same config across different developers has to work with different credentials.

What to remember about the server environment: it is not your shell. The client launches the process itself, and variables you exported in a terminal are invisible to it. They must be set where the client will pick them up, usually in the server entry itself.

Another common trap: an empty variable is indistinguishable from a missing one. The server starts, cannot authenticate, and returns an empty tool list. From outside that looks like “connected but not working”.

Logs

Three places to look.

The client log. Shows whether the process started and how it exited. First stop when the server is missing from the list.

Server output on stderr. Standard output belongs to the protocol, so everything diagnostic goes to stderr. If you are writing your own server, any print to stdout breaks the exchange - the most common beginner mistake.

The server file log. The most useful option for your own server: it shows which tool was called, with what arguments, and what came back. Without it, diagnosing “the agent did the wrong thing” is impossible.

A good habit: log the call arguments. Half the problems turn out not to be in the server but in the agent passing something you did not expect, and the cause is the tool description.

Common errors

Symptom	Cause
Server missing from the list	Client not restarted, or broken JSON
Server marked as failed	Command not found; use the full path
Server live, no tools	Authentication failed: check the variables
Tools present, agent ignores them	Vague descriptions
Works for you, not for a colleague	Config is user-level rather than project-level
Works but slowly	The server calls an external system on every invocation
Agent picks the wrong tool	Two servers with similar tool names

On that last one: name collisions are fixed by disconnecting the surplus server, not by refining the prompt. If two servers expose similar tools, the agent will keep getting it wrong regardless of wording.

Debugging order

1. Run the server command by hand in a terminal.
2. Validate the config syntax.
3. Restart the client.
4. Check the server status in the list.
5. Ask the agent for its tool list.
6. Make one safe call.

Each step eliminates a class of causes, and together they cover nearly everything. Local specifics are in local server. The overview is in the MCP guide.