How to Connect Claude Code to Tools via MCP
.mcp.json in your project root makes servers available in that project only. A global entry in ~/.claude/settings.json makes servers available across all projects. Both local stdio servers and remote HTTP servers are supported.
Before You Start
You need Claude Code installed and a working MCP server to connect to. The server can be one you built yourself, a community server, or a hosted service like Adaptive Recall. You need the connection details: for a local server, the command and arguments to start it; for a remote server, the URL and authentication credentials.
Step-by-Step Configuration
Project-level servers are defined in a
.mcp.json file in the project root directory. They only load when you open that project. Global servers are defined in ~/.claude/settings.json and load for every project. Use project scope for servers tied to a specific codebase (like a custom file analyzer). Use global scope for servers you want everywhere (like a memory system or a general-purpose search tool).
For project scope, create
.mcp.json in your project root. For global scope, open ~/.claude/settings.json (create it if it does not exist). Both files use the same JSON structure for the mcpServers object.
The configuration format depends on the transport type. For a local stdio server, specify the command and arguments to launch the server process. For a remote HTTP server, specify the URL and any authentication headers.
Local stdio server (runs as a subprocess):
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["./tools/server.py"],
"env": {
"DATABASE_URL": "postgres://localhost/mydb"
}
}
}
}Remote HTTP server (connects over the network):
{
"mcpServers": {
"adaptive-recall": {
"type": "url",
"url": "https://mcp.adaptiverecall.com/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}Claude Code reads MCP configuration at startup. After adding or changing a server configuration, start a new session. Claude Code connects to each configured server, sends the initialization handshake, and registers the discovered tools, resources, and prompts. If a server fails to connect, Claude Code logs the error and continues with the remaining servers.
Ask Claude to use one of the tools from your server. For example, if you connected a memory server, ask "What do you remember about this project?" The model should invoke the recall tool and return results. If the tools do not appear, check the Claude Code logs for connection errors and verify that the server starts correctly when run manually with the configured command.
Multiple Servers
You can connect multiple MCP servers simultaneously. Each server entry in the mcpServers object is independent, and Claude Code connects to all of them at startup. Tools from different servers appear together in the available tools list, and the model can invoke tools from any connected server within a single conversation.
{
"mcpServers": {
"memory": {
"type": "url",
"url": "https://mcp.adaptiverecall.com/mcp",
"headers": {"Authorization": "Bearer key-1"}
},
"database": {
"command": "python",
"args": ["./tools/db_server.py"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": "ghp_your_token"}
}
}
}Keep server names unique and descriptive. The name is what appears in tool listings and logs, so "memory" is better than "server1" when you need to debug why a tool call failed.
Combining Project and Global Servers
When both project-level and global configurations exist, Claude Code merges them. Global servers load first, then project-level servers add to or override the global list. If a project defines a server with the same name as a global server, the project configuration takes precedence for that project.
A common pattern is to define your personal memory server globally (available everywhere) and define project-specific tools in each project's .mcp.json. This gives you persistent memory across all projects plus specialized tools for each codebase.
Troubleshooting Connection Issues
The most common connection problems and their solutions:
Server not found: The command in the configuration does not exist on the PATH. Verify by running the exact command from the terminal. Use absolute paths if the command is in a virtual environment or non-standard location.
Server starts but tools do not appear: The server process starts but fails during initialization, often because of missing environment variables or dependency imports. Run the server manually and check for startup errors.
HTTP connection refused: The URL is wrong, the server is not running, or a firewall is blocking the connection. Test with curl: curl -X POST https://your-server/mcp should return a JSON-RPC response, not a connection error.
Authentication failures: The API key or token is invalid, expired, or missing. Check that the Authorization header is correctly formatted and the key has not been rotated since configuration.
Tools work in Inspector but not in Claude Code: The server works standalone but the client configuration is slightly wrong. Compare the exact command, arguments, and environment between your Inspector test and the client configuration. Path differences are the most common cause.
Add persistent memory to every Claude Code session. Adaptive Recall connects in two minutes with a single configuration entry.
Get Started Free