---

name: claude-code-mcp description: Configure and build Model Context Protocol (MCP) servers for Claude Code integration. Set up database, filesystem, git, and API connections. Build custom MCP servers with TypeScript/Python SDK, implement tools and resources, configure transports (stdio, HTTP), and deploy for production.

Claude Code MCP — Complete Reference

Specification: MCP 2025-11-25 (November 2025)

This skill provides the definitive reference for configuring and building MCP servers in Claude Code. Use this when:

• Connecting Claude to databases, filesystems, APIs, or other external data sources
• Building custom MCP servers for proprietary integrations
• Deploying MCP servers to production (OAuth 2.1 + CIMD required for HTTP)

---

Quick Reference

Configuration Location

Copy.claude/
└── .mcp.json    # MCP server configuration

---

Configuration Schema

Copy{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@scope/package-name"],
      "env": {
        "VAR_NAME": "${ENV_VAR}"
      }
    }
  }
}

---

Official MCP Servers

PostgreSQL

Copy{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "${DATABASE_URL}"
      }
    }
  }
}

Capabilities:

• Execute SELECT queries
• List tables and schemas
• Describe table structure

Filesystem

Copy{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/allowed/path1",
        "/allowed/path2"
      ]
    }
  }
}

Capabilities:

• Read files in allowed paths
• List directory contents
• Search file contents

Security: Paths are allowlisted—Claude can only access specified directories.

Git

Copy{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"],
      "env": {
        "GIT_DIR": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}

Capabilities:

• Git status and diff
• Commit history
• Branch information

Brave Search

Copy{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Capabilities:

• Web search
• News search
• Local search

Slack

Copy{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

Capabilities:

• List channels
• Read messages
• Search conversations

---

Environment Variables

Reference Syntax

Copy{
  "env": {
    "VAR_NAME": "${ENVIRONMENT_VARIABLE}"
  }
}

The ${VAR} syntax references environment variables from your shell.

Setting Variables

Copy# .env file (project-level)
DATABASE_URL=postgresql://user:pass@localhost:5432/db
BRAVE_API_KEY=BSA...

# Export in shell
export DATABASE_URL="postgresql://..."

---

Multiple Servers

Copy{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_URL": "${DATABASE_URL}" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

---

Custom MCP Servers

Local Server

Copy{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./mcp-servers/my-server/dist/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Python Server

Copy{
  "mcpServers": {
    "python-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {}
    }
  }
}

---

CLI Commands

Manage MCP servers from the command line:

Copy# Add server (HTTP transport - recommended for remote)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add server (stdio transport - for local)
claude mcp add postgres --env POSTGRES_URL=postgresql://... -- npx -y @modelcontextprotocol/server-postgres

# List configured servers
claude mcp list

# Remove server
claude mcp remove notion

# Test server connection
claude mcp get notion

# Enable/disable servers (inside Claude Code session)
/mcp enable 1    # Enable server at index 1
/mcp disable 2   # Disable server at index 2

Permission Management

Copy# Allow all tools from a specific server (wildcard)
claude mcp add --allow "mcp__postgres__*" postgres -- npx -y @modelcontextprotocol/server-postgres

# Allow specific tools only
claude mcp add --allow "mcp__postgres__query,mcp__postgres__list_tables" postgres -- ...

# Deny specific tools
claude mcp add --deny "mcp__filesystem__write_file" filesystem -- ...

---

Transport Types

HTTP (Recommended for Remote)

Copyclaude mcp add --transport http notion https://mcp.notion.com/mcp

Or in .mcp.json:

Copy{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "transport": "http"
    }
  }
}

stdio (Default for Local)

CopyClaude Code ←→ stdin/stdout ←→ MCP Server

Most common for local servers. Process runs as child of Claude Code.

SSE (Legacy Remote)

Copy{
  "mcpServers": {
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "transport": "sse"
    }
  }
}

For networked MCP servers (prefer HTTP for new integrations).

---

Token Limits

MCP tool outputs are monitored for size:

Override maximum:

CopyMAX_MCP_OUTPUT_TOKENS=50000 claude

---

Security Considerations

See references/mcp-security.md for the complete security hardening guide.

CopyMCP SECURITY CHECKLIST (November 2025)

Authentication (HTTP transports)
[ ] OAuth 2.1 mandatory for HTTP
[ ] Client ID Metadata Documents (CIMD) for registration
[ ] Resource Indicators (RFC 8707) for token scoping

Secrets Management
[ ] Use MCP Secret Wrapper or vault integration
[ ] No static secrets in config files
[ ] Environment variable injection at runtime

Access Control
[ ] Zero-trust model - validate every request
[ ] Minimal permissions (incremental scopes)
[ ] Scoped filesystem access
[ ] Read-only database by default

Credential Management

Copy# RECOMMENDED: Use MCP Secret Wrapper (no secrets in config)
mcp-secret-wrapper --vault aws-secrets-manager --secret-id mcp/db-url --server @modelcontextprotocol/server-postgres

# Alternative: Use secret managers
export DATABASE_URL="$(aws secretsmanager get-secret-value --secret-id db-url | jq -r .SecretString)"

# Development only: .env files (gitignored)
source .env

---

Troubleshooting

Debug Mode

Copy# Test MCP server manually
npx -y @modelcontextprotocol/server-postgres

# Check server logs
CLAUDE_MCP_DEBUG=1 claude

---

Navigation

Resources

• references/mcp-servers.md — Complete server list
• references/mcp-custom.md — Building custom servers
• references/mcp-patterns.md — Common integration patterns
• references/mcp-security.md — Security hardening guide

Templates (Copy-Paste Ready)

• assets/database/template-mcp-database.md — PostgreSQL/MySQL MCP server
• assets/api/template-mcp-api.md — REST/GraphQL API integration
• assets/filesystem/template-mcp-filesystem.md — Scoped file access
• assets/deployment/template-mcp-docker.md — Docker + Kubernetes deployment

Related Skills

• ../data-sql-optimization/SKILL.md — Database patterns
• ../software-backend/SKILL.md — API integration
• ../software-security-appsec/SKILL.md — Security patterns