Claude Code MCP Setup

Updated May 2026 · Model Context Protocol servers for Claude Code

MCP (Model Context Protocol) is the plugin system for Claude Code. Each MCP server exposes tools Claude can call — query a Postgres database, search the web, control a browser, read Slack messages. This page covers setup from zero to using your first MCP tool inside Claude Code.

What MCP Actually Does

Without MCP, Claude Code can only read and edit files in your project directory plus run shell commands. With MCP servers connected, Claude Code gets callable functions that reach outside the filesystem:

Config File Location

Claude Code looks for MCP server configuration in two places:

• ~/.claude/settings.json — user-global (applies to every project)
• .claude/settings.json — project-scoped (checked into the repo, applies only here)

Project-scoped config merges with user-global (it does not replace it). Use project-scoped for servers specific to a codebase (like the project's Postgres DB) and user-global for personal tools (your Slack, personal GitHub token).

Quick Start: Filesystem MCP Server

The filesystem server is the simplest to set up and the safest to try first. It lets Claude read and write files outside your project directory (e.g., your home Documents folder).

# Install
npm install -g @modelcontextprotocol/server-filesystem

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Desktop"
      ]
    }
  }
}

Restart Claude Code. Type /mcp to confirm the server appears. Now you can say "read ~/Documents/notes.md" and Claude will call the filesystem tool directly.

PostgreSQL MCP Server

The most-used MCP server for developers. Lets Claude query your database, inspect the schema, and write migrations based on actual table structure.

# Install
npm install -g @modelcontextprotocol/server-postgres

Add to .claude/settings.json in your project (so the DB connection is repo-scoped):

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

Once connected, Claude can answer questions like "what tables reference user_id?" or "write a migration to add an index on orders.created_at" with actual schema context instead of guessing.

GitHub MCP Server

Gives Claude read access to GitHub repos, issues, PRs, and code — including private repos your token can access.

# Install
npm install -g @modelcontextprotocol/server-github

Add to ~/.claude/settings.json (user-global since it uses your personal token):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Useful prompts after connecting:

• "Summarize the open PRs in myorg/myrepo that touch the auth module"
• "Find all issues labeled 'bug' opened in the last 7 days"
• "What changed between main and the feature/payments branch?"

Building a Custom MCP Server

If none of the pre-built servers fit your tool, write your own. The TypeScript SDK is the recommended path.

npm install @modelcontextprotocol/sdk

// my-mcp-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "get_feature_flag",
    description: "Check if a feature flag is enabled in our LaunchDarkly account",
    inputSchema: {
      type: "object",
      properties: {
        flag_key: { type: "string", description: "LaunchDarkly flag key" }
      },
      required: ["flag_key"]
    }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_feature_flag") {
    const key = request.params.arguments?.flag_key as string;
    // Call your internal API here
    const enabled = await checkFeatureFlag(key);
    return { content: [{ type: "text", text: `Flag ${key}: ${enabled}` }] };
  }
  throw new Error("Unknown tool");
});

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

Register it in .claude/settings.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/my-mcp-server.ts"]
    }
  }
}

Debugging MCP Connections

If a server doesn't appear in /mcp, check these in order:

1. JSON syntax — a trailing comma in settings.json silently breaks parsing. Validate with jq . ~/.claude/settings.json.
2. Command path — run the command + args yourself in a terminal. If it errors, Claude Code will silently skip the server.
3. Node version — most MCP servers require Node 18+. Check with node --version.
4. Permissions — on macOS, npx must be allowed to run in Claude Code's permission settings.

# Quick validation: does the server start without errors?
npx @modelcontextprotocol/server-postgres "postgresql://localhost/mydb"
# Should output: "MCP server running on stdio" (CTRL+C to exit)

Security Model

MCP tools run with the same OS-level permissions as the user running Claude Code. There is no sandboxing between Claude and MCP tools. Key rules:

• Only connect MCP servers you trust — they can read and write anything they expose
• Use read-only DB credentials for the postgres server
• Never add MCP servers with write access to production systems in CI pipelines
• Review the source of any third-party MCP server before running it

FAQ

What is MCP in Claude Code?

MCP (Model Context Protocol) is an open standard that lets Claude Code connect to external tools and data sources. Each MCP server exposes tools (functions Claude can call) and resources (data Claude can read). Examples: a PostgreSQL MCP server lets Claude query your database; a GitHub MCP server lets Claude read issues and PRs.

Where does Claude Code store MCP server config?

Claude Code reads MCP server configuration from .claude/settings.json in your project root (project-scoped) or ~/.claude/settings.json (user-global). The mcpServers key maps server names to their command and args. Project-scoped config takes precedence and can override user-global servers.

How do I list all available MCP tools in Claude Code?

Run /mcp in the Claude Code chat to list all connected MCP servers and their available tools. Each tool shows its name, description, and input schema. You can also ask Claude directly: "What MCP tools do you have access to?"

Can I write my own MCP server for Claude Code?

Yes. The MCP SDK is available for TypeScript (npm install @modelcontextprotocol/sdk) and Python (pip install mcp). A minimal server needs a name, version, and at least one tool defined with a JSON schema for its inputs. Claude Code will discover and call it automatically once it's registered in settings.json.

Is there a list of pre-built MCP servers for Claude Code?

Yes. Anthropic maintains an official list at github.com/modelcontextprotocol/servers. Popular ones include: filesystem, postgres, github, brave-search, puppeteer, and sqlite. Third-party directories also exist at mcpservers.org and smithery.ai.