How do you configure Claude Desktop (or another host) to launch a local MCP server?
Quick Answer
For Claude Desktop, you add an entry under mcpServers in its configuration file (claude_desktop_config.json, found in the app's config directory), specifying a command (the executable to run, e.g. python or npx) and args (the script path and any startup arguments), plus optional env for environment variables like API keys the server needs. On restart, the host launches each configured server as a subprocess over stdio and performs the initialize handshake automatically; if the process fails to start or crashes, most hosts surface that as a connection error in their UI or logs rather than silently ignoring it.
Detailed Answer
Connecting a locally built server to a host is mostly a matter of telling the host what command to run.
Example config
{
"mcpServers": {
"notes-server": {
"command": "python",
"args": ["/absolute/path/to/server.py"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
}
}
What the host does with this
On startup, or after a config reload, the host spawns each listed command as a child process. It connects a stdio transport to its stdin/stdout, then runs the initialize handshake. Once connected, that server's tools, resources, and prompts become available in the conversation, typically shown in a UI element listing active connections.
Common configuration pitfalls
- Relative paths. The host may launch the process from a different working directory than expected. An
argsentry like"./server.py"can fail to resolve, so absolute paths are safer. - Missing dependencies on PATH. Say the host launches
python, but the machine's shell environment (where dependencies were installed) isn't the same environment the host process inherits. Imports fail silently from the host's perspective — it just sees the server exit immediately. - Secrets in plaintext config.
envvalues like API tokens sit in a plaintext JSON file on disk. Treat that file with the same care as any other credentials store, and prefer OS-level secret managers where a host supports referencing them instead of literal values.
Debugging a server that won't connect
Most hosts write server stderr output, and connection failures, to a log file the user can inspect. Checking there is usually the fastest way to find out whether the process failed to start at all, crashed during the handshake, or connected but failed on a specific request.