Claude Code MCP Servers: How to Connect Any Tool to Your AI Coding Assistant

Update — July 16, 2026: Published Claude Code artifacts can call claude.ai remote connectors on every page load — viewer-scoped auth, not your session's local .mcp.json servers. See Claude artifacts + MCP connectors.

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.

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:

1. Ask the server to list its available tools
2. Call any tool with a JSON payload matching that tool's input schema
3. 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:

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:

.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.

MCP Config Format

Both methods use the same JSON structure:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

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:

npm install -g @modelcontextprotocol/server-postgres
npm install -g @modelcontextprotocol/server-github

Popular MCP Servers

@wonderwhy-er/desktop-commander — terminal + filesystem + surgical edits

The 7.8k-star community server that extends MCP filesystem with interactive terminal sessions, ripgrep search, edit_block fuzzy patches, Excel/PDF/DOCX, and Claude Desktop file preview UI. Works in Claude Code, Cursor, Codex, and Remote MCP. Full setup: Desktop Commander MCP guide.

"desktop-commander": {
  "command": "npx",
  "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
}

@modelcontextprotocol/server-filesystem

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.

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
}

@modelcontextprotocol/server-github

Read and write access to GitHub. Claude can list open PRs, read issue comments, create issues, post review comments, and check CI status.

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "ghp_yourtokenhere" }
}

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.

"postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://readonly_user:password@localhost:5432/mydb"
  ]
}

@modelcontextprotocol/server-brave-search

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.

"brave-search": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": { "BRAVE_API_KEY": "your-brave-api-key" }
}

Get a free API key at brave.com/search/api.

@modelcontextprotocol/server-slack

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.

"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
    "SLACK_TEAM_ID": "T01234567"
  }
}

Enterprise Integrations: Ahrefs, Vercel, PostHog

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.

Vercel — query deployments, fetch build logs, manage environment variables:

"vercel": {
  "command": "npx",
  "args": ["-y", "@vercel/mcp-server"],
  "env": { "VERCEL_TOKEN": "your-vercel-token" }
}

PostHog — query analytics, pull event data, check feature flag states:

"posthog": {
  "command": "npx",
  "args": ["-y", "@posthog/mcp-server"],
  "env": {
    "POSTHOG_API_KEY": "phx_your_key",
    "POSTHOG_HOST": "https://us.posthog.com"
  }
}

Ahrefs — SEO data, keyword metrics, backlink analysis directly inside Claude:

"ahrefs": {
  "command": "npx",
  "args": ["-y", "@ahrefs/mcp-server"],
  "env": { "AHREFS_API_KEY": "your-ahrefs-key" }
}

Project-Level vs. User-Level Config

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:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://app_user:secret@localhost:5432/app_development"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_projectspecifictoken" }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "BSA_yourkeyhere" }
    }
  }
}

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:

/mcp

Claude will list every connected server and the tools it exposes. A healthy output looks like:

Connected MCP servers:

postgres
  Tools: query, list_tables, describe_table

github
  Tools: list_issues, get_issue, create_issue, list_pull_requests, get_pull_request, create_review_comment

brave-search
  Tools: web_search

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:

npm install @modelcontextprotocol/sdk

A minimal TypeScript server with one tool:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { 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 API
    const status = await fetchOrderStatus(orderId);
    return { content: [{ type: "text", text: JSON.stringify(status) }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Point your Claude config at the compiled script:

"my-api": {
  "command": "node",
  "args": ["/path/to/dist/server.js"],
  "env": { "INTERNAL_API_KEY": "your-key" }
}

For full documentation, examples, and the Python SDK, see modelcontextprotocol.io.

A Full Working Config

Here is a complete .claude/settings.json you can adapt for most web development projects:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://dev_user:devpass@localhost:5432/myapp_development"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_replace_with_your_token" }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "replace_with_your_brave_key" }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-replace-with-bot-token",
        "SLACK_TEAM_ID": "T00000000"
      }
    }
  }
}

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.