Claude Code MCP Servers: How to Connect Any Tool to Your AI Coding Assistant
Learn how to connect external tools, databases, APIs, and services to Claude Code using the Model Context Protocol (MCP). Step-by-step configs, popular servers, security tips, and troubleshooting.
Update — June 30, 2026: X shipped hosted MCP at api.x.com/mcp — add it to Claude Desktop or Claude Code with the xurl bridge. Step-by-step: X hosted MCP servers guide.
Claude Code is already useful for reading and writing files. MCP makes it genuinely powerful. With the right servers connected, Claude can query your production database, search the web, pull up open GitHub issues, check your Vercel deployment logs, and read the Slack thread where someone reported the bug—all without you leaving the conversation.
This guide covers everything you need: what MCP is, how to configure it, which servers to install first, security considerations, and how to fix it when something goes wrong.
What Is MCP?
Model Context Protocol is an open standard created by Anthropic that defines how AI models communicate with external tools and services. Think of it as a universal adapter between Claude and the rest of your development environment.
Before MCP, Claude could only work with what you explicitly pasted into the conversation or with files it could read on disk. MCP removes that ceiling. Any data source or service that wraps itself in an MCP server becomes something Claude can directly query and act on.
The protocol is intentionally simple. An MCP server exposes a list of tools—named functions with typed input schemas. When Claude decides it needs one of those tools, it calls the function, gets the result back, and reasons over it just like any other context. From Claude's perspective, calling a postgres MCP tool to run a SQL query is no different from calling its built-in file-read tool.
MCP is open source and provider-agnostic. The growing ecosystem of servers is maintained by Anthropic, major SaaS companies, and the community.
Why It Matters for Claude Code
Here is the practical difference MCP makes in everyday workflows.
The conceptual foundation behind MCP server connections — what they enable and why.
Without MCP, debugging a production issue looks like this: copy the error from Sentry, paste it into Claude, copy the relevant database schema, paste it, manually write out what the Slack thread said, ask Claude to help diagnose it.
With MCP, you ask: "There's a 500 error on the /checkout endpoint. Check the postgres logs table for errors in the last hour, look at the open GitHub issues for anything related, and tell me what's causing it." Claude calls the postgres server, queries the logs, calls the GitHub server, searches issues, and gives you a diagnosis with the actual data in front of it.
The pattern extends to any workflow: generate a migration and run it, read a PR's diff and write a review comment, pull PostHog event data and add instrumentation to the code path that needs it.
How MCP Works Under the Hood
When Claude Code starts up, it reads your MCP config and launches each configured server as a local subprocess. The server process stays running in the background for the lifetime of your Claude session.
The subprocess communicates with Claude over stdin/stdout using the MCP wire format. During the session, Claude can:
Ask the server to list its available tools
Call any tool with a JSON payload matching that tool's input schema
Receive a structured result back
The server itself is responsible for making the actual API call, database query, or filesystem operation. Claude only sees the result. This means you can point the same postgres MCP server at different databases by changing the connection string in your config, without Claude needing to know anything changed.
Adding MCP Servers to Claude Code
There are two ways to configure MCP servers.
Option 1: --mcp-config flag
Pass a path to a JSON config file when launching Claude Code:
bash
claude --mcp-config ~/.config/claude/mcp.json
This is useful for a global set of servers you want available everywhere, without touching any project files.
Option 2: .claude/settings.json
Add an mcpServers block to the settings file inside your project directory:
snippet
.claude/
settings.json
Project-level config is scoped to that repo, which is useful when a server (like postgres) should only connect to a specific project's database.
Each key under mcpServers is the name you give the server (used in /mcp output). The command and args tell Claude how to launch it. The optional env block injects environment variables into that subprocess only.
You do not need to pre-install the packages. The -y flag on npx handles that automatically on first run. For servers you use frequently, install them globally to avoid the startup delay:
Enhanced file operations beyond what Claude can do natively. Useful for projects with complex directory structures or when you want explicit control over which paths Claude can access.
Use a fine-grained personal access token scoped to the repos you need.
@modelcontextprotocol/server-postgres
Direct read/write access to a PostgreSQL database. Claude can run arbitrary SQL, inspect schemas, and reason over query results. Pair this with careful permissions on the database user—create a read-only role if you only need Claude to inspect data.
Web search inside Claude Code. Useful when you need Claude to look up docs, check changelogs, or research an unfamiliar library without you pasting content manually.
Read and post to Slack channels and DMs. Claude can pull the context from a #bugs thread, draft a deployment announcement, or check whether someone already reported an issue.
The MCP ecosystem includes first-party servers from major platforms. These are configured the same way but typically require API keys from their respective dashboards.
User-level config lives in ~/.claude/settings.json (or wherever you pass --mcp-config). Use it for servers you want everywhere—Brave Search and GitHub are good candidates since they're context-independent.
Project-level config lives in .claude/settings.json inside the repo. Use it for servers tied to a specific project—the postgres connection string that points at this project's database, the Vercel token scoped to this team, the PostHog key for this product.
A complete project .claude/settings.json might look like this:
If you commit this file, add real secrets to .gitignore and use environment variable references or a secrets manager instead of hardcoding values.
Security: What You Need to Know
MCP servers run as local processes under your user account. They are not sandboxed by Claude. A malicious MCP server could read files, make network requests, or do anything else your user account can do.
Practical rules:
Only add servers you trust. Treat npx @some-package/mcp-server the same as globally installing any npm package. Check the package source and maintainer.
Use minimal database permissions. If Claude only needs to read data, connect with a read-only database user. Do not use a superuser connection string.
Scope tokens narrowly. GitHub tokens should be fine-grained and limited to specific repos. Vercel tokens should be team-scoped, not account-scoped.
Do not commit secrets. Use environment variables or a tool like 1Password CLI / direnv to inject secrets at runtime rather than writing them into config files.
Check what tools a server exposes. Before adding an unfamiliar server, use /mcp after connecting to see exactly what Claude can call.
Verifying MCP Is Working
Once Claude Code is running with your config, type:
snippet
/mcp
Claude will list every connected server and the tools it exposes. A healthy output looks like:
If a server is missing from this list, it did not connect successfully. If it is listed but shows no tools, the server process started but failed during tool registration. Both are starting points for troubleshooting.
Troubleshooting Common Problems
Server not appearing in /mcp
Confirm npx is in your PATH: which npx
Run the server command manually in a terminal to see its startup output: npx -y @modelcontextprotocol/server-github
Check for typos in the package name in your config
If using a global install, make sure it completed: npm list -g @modelcontextprotocol/server-github
Tools listed but not working
Check that required environment variables are set: the server probably logged an error about a missing API key
Verify the API key or token is valid by using it in a direct curl request
Look at what the tool returns when called — Claude will usually surface the error message
Server connects but Claude does not use it
Be explicit in your prompt: "use the postgres MCP server to query the users table"
Make sure the tool descriptions are clear enough for Claude to understand when to invoke them (this matters more for custom servers)
Connection string issues (postgres)
Test the connection string directly: psql "postgresql://user:pass@localhost:5432/db"
Make sure the postgres server process can reach the database host (VPN, firewall rules)
Building a Custom MCP Server
The official MCP SDK makes this straightforward. Install it:
bash
npm install @modelcontextprotocol/sdk
A minimal TypeScript server with one tool:
typescript
import { Server } from"@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from"@modelcontextprotocol/sdk/server/stdio.js";
const server = newServer(
{ name: "my-internal-api", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
server.setRequestHandler("tools/list", async () => ({
tools: [{
name: "get_order_status",
description: "Look up the status of an order by order ID",
inputSchema: {
type: "object",
properties: {
order_id: { type: "string", description: "The order ID" }
},
required: ["order_id"]
}
}]
}));
server.setRequestHandler("tools/call", async (request) => {
if (request.params.name === "get_order_status") {
const orderId = request.params.arguments.order_id;
// Call your internal APIconst status = awaitfetchOrderStatus(orderId);
return { content: [{ type: "text", text: JSON.stringify(status) }] };
}
});
const transport = newStdioServerTransport();
await server.connect(transport);
Replace the placeholder values, start a Claude Code session in the project root, and verify with /mcp.
Conclusion
MCP is the feature that moves Claude Code from "smart file editor" to "developer that has access to your whole stack." The setup cost is low — a few lines of JSON and an API token — and the productivity payoff starts immediately once Claude can query your database or pull context from GitHub without you having to copy-paste it.
Start with the servers most relevant to your daily friction: GitHub if you constantly switch to the browser to look up issues, postgres if you spend time manually checking data, Brave Search if you regularly paste docs into the chat. Add others as the need arises.
The /mcp command is your best friend for verifying what is connected and diagnosing problems. And if no server exists for a tool you use, the official SDK makes it practical to build your own in under an hour.
