Claude Desktop can connect to MCP servers through a local configuration file. That config tells Claude which server command to run, which arguments to pass, and which environment variables the server needs.
This guide explains the shape of a Claude MCP server config without pretending to be official Anthropic documentation. Always confirm exact file locations and client behavior with the current Claude Desktop docs for your operating system.
Key takeaways
- A Claude MCP config entry usually defines a server name, command, args, and optional env values.
- Most failures come from wrong command paths, missing runtimes, missing tokens, or forgetting to restart Claude Desktop.
- Keep config entries narrow and avoid giving write-capable servers unnecessary credentials.
What a Claude MCP server config does
The config is a launch map. Claude Desktop reads the server entries, starts the listed commands, and discovers the tools each server exposes. If the command fails, Claude cannot see the tools. If the server starts but requires missing credentials, the tools may appear but fail when called.
The server name should be human-readable because it helps users understand what capability is being added. A name like filesystem, github, docs-search, or json-tools is easier to audit than a vague name like helper.
Common config shape
A typical config entry includes mcpServers at the top level. Each server has a command and optional args. Some servers also need env variables for API tokens or paths. The exact command depends on the package and runtime.
Treat the following as an illustrative structure, not a universal copy-paste block. Check the server README before adding it to a real config.
{
"mcpServers": {
"docs-search": {
"command": "node",
"args": ["/path/to/server.js"],
"env": {
"DOCS_INDEX_PATH": "/path/to/docs-index"
}
}
}
}Safe config rules
The config file is powerful because it can launch local processes. That means you should only add servers you trust and understand. Read the server source or at least the README, check what tools it exposes, and start with read-only access when possible.
If a server needs an API token, prefer the narrowest token scope available. Do not add production admin credentials to a local assistant config unless there is a strong reason and a review process.
- Use descriptive server names.
- Prefer absolute paths for local scripts when setup is failing.
- Keep secrets in env values, not inside prompts.
- Avoid broad write permissions during first setup.
- Remove unused servers instead of leaving stale entries enabled.
Troubleshooting Claude MCP config
If the server does not show up, first verify the command works from a terminal. Then verify the same runtime is available to the Claude Desktop process. A command that works in your shell may fail in a GUI app if PATH is different.
If the server appears but tool calls fail, check environment variables, file permissions, API token scopes, and server logs. If only one tool fails, the issue is probably inside the server or input schema rather than the client config.
- Restart Claude Desktop after editing the config.
- Check JSON syntax before relaunching.
- Use absolute command paths when PATH is inconsistent.
- Confirm the package version supports your client.
- Disable one server at a time to isolate failures.
When to create a separate config entry
Separate config entries are useful when servers have different trust levels or workflows. For example, a read-only docs server and a write-capable deployment server should not be treated as the same integration. Splitting them makes approval decisions clearer.
For teams, the config should be documented like any other developer environment file. Include the server purpose, install command, required environment variables, and test prompt so new users can verify setup quickly.
Implementation review before you use this guide
Treat this Claude MCP Server Config guide as a practical starting point, not as a replacement for the current server README, client documentation, or your own production review. MCP clients, SDKs, hosted transports, package names, and security defaults can change quickly. Before you recommend a server or copy a configuration into a real workflow, verify the exact package version, supported client, command path, required credentials, and exposed tool list.
For BestMCPServers, the durable evaluation standard is simple: the page should help a builder complete a real task safely. That means clear setup steps, honest limitations, useful troubleshooting notes, internal links to related MCP guides, and no unsupported claim that a feature is official or already hosted. If the topic touches credentials, private data, deployment, or write actions, start with read-only behavior, document the trust boundary, and add stronger review before production use. When a page is used for SEO validation, keep the content useful for the same developer who arrived from search: answer the immediate setup question, show the safer alternative, explain the failure modes, and point to the next guide only after the core task is clear.
- Verify the current upstream docs and package version.
- Test one narrow prompt before expanding the workflow.
- Keep secrets out of prompts, screenshots, logs, and public examples.
- Document what the server can read, write, call, and return.
FAQ
Where is the Claude MCP config file?
The location depends on your operating system and Claude Desktop version. Check the current Claude Desktop MCP documentation, then verify you are editing the config used by the running app.
What goes inside mcpServers?
Each entry typically includes a server name, command, optional args, and optional env values. The exact fields depend on the server package.
Why does my Claude MCP server fail to start?
Common causes include invalid JSON, wrong command path, missing Node.js or Python runtime, missing package, missing env variable, or a command that works in the shell but not in the desktop app environment.
Should I put API keys in Claude MCP config?
Only when the server requires them, and only with the narrowest practical scope. Avoid broad production admin tokens for experimental local setups.
Is this official Claude documentation?
No. This is an independent BestMCPServers guide. Use it as a practical checklist and confirm exact details with official Anthropic documentation.