Claude Code × MCP Integration Guide

MCP (Model Context Protocol) allows connecting Claude Code to tools such as the file system, databases, and external APIs, significantly expanding the range of tasks it can perform autonomously.

What Is Claude Code × MCP?

MCP (Model Context Protocol) is an open protocol that provides AI models with standardized access to external tools and data sources. Anthropic led its development, and it has since become an open standard with adoption from many tool vendors.

Claude Code supports file operations, shell commands, and git out of the box. Adding MCP servers significantly extends the range of tools available.

graph TD
  CC[Claude Code] --> |MCP protocol| MCP1[GitHub MCP Server]
  CC --> |MCP protocol| MCP2[Filesystem MCP Server]
  CC --> |MCP protocol| MCP3[SQLite MCP Server]
  CC --> |MCP protocol| MCP4[Slack MCP Server]
  CC --> |MCP protocol| MCP5[Custom MCP Server]

  MCP1 --> T1[PR creation, issue management, review]
  MCP2 --> T2[File access outside the project directory]
  MCP3 --> T3[SQL queries, schema inspection]
  MCP4 --> T4[Send messages, read channels]
  MCP5 --> T5[Connect to custom APIs]

Core MCP concepts:

• MCP server: A process that provides tools (runs locally or remotely)
• MCP client: The component that calls MCP servers (Claude Code acts as the client)
• Tool definition: The specification of a capability provided by an MCP server (name, input parameters, description)

---

MCP Server Categories

MCP servers are grouped by function into the following categories.

File System

Server	Capability	Primary use
@modelcontextprotocol/server-filesystem	Read/write local files, directory operations	Access directories outside the current project
@modelcontextprotocol/server-memory	In-memory key-value store	Persist information across sessions

Databases

Server	Capability	Primary use
@modelcontextprotocol/server-sqlite	Read/write SQLite databases	Operate and analyze local databases
@modelcontextprotocol/server-postgres	Connect to PostgreSQL	Query development or staging databases

Web and Search

Server	Capability	Primary use
@modelcontextprotocol/server-brave-search	Web search via Brave Search API	Research and information gathering
@modelcontextprotocol/server-fetch	Fetch URLs and retrieve web pages	Reference documentation, verify API connectivity

Development Tools

Server	Capability	Primary use
@modelcontextprotocol/server-github	GitHub PR, issue, and code operations	Automate PR creation and review
@modelcontextprotocol/server-gitlab	GitLab MR, issue, and pipeline operations	Automation for teams using GitLab
mcp-atlassian	Jira and Confluence operations	Task management and documentation reference

Communication

Server	Capability	Primary use
@modelcontextprotocol/server-slack	Slack message sending/receiving, channel operations	Automate notifications and information sharing
@gcp/google-workspace-mcp	Gmail, Google Docs, Sheets operations	Document creation and email automation

---

Configuring MCP in settings.json

MCP configuration is specified in the mcpServers section of Claude Code’s settings.json. This file is typically located at .claude/settings.json (project level) or ~/.claude/settings.json (global).

Basic Configuration Structure

{
  "mcpServers": {
    "server-name": {
      "command": "executable command",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR_NAME": "value"
      }
    }
  }
}

Local MCP Server Configuration Example

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents",
        "/Users/username/Projects"
      ]
    },
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "/Users/username/data/mydb.sqlite"
      ]
    }
  }
}

Remote MCP Server Configuration Example (SSE/HTTP)

{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Note: Environment variables in the ${VAR_NAME} format are expanded within settings.json. API keys and tokens should never be written directly in settings.json; always reference them via environment variables.

---

Configuration Examples for Common MCP Servers

GitHub MCP (PR Creation and Issue Management)

Configuring the GitHub MCP server allows Claude Code to create PRs, reference issues, and post review comments.

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

Setting the required environment variable:

# Add to ~/.zshrc or ~/.bashrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

Operations enabled by GitHub MCP:

• Automatically create a PR from the current branch
• Search for and reference related issues
• Post review comments on a PR
• Browse a repository’s file structure (without git clone)

---

Filesystem MCP (Access Outside the Project Directory)

Claude Code can access files within the current project directory by default. The Filesystem MCP enables access to files in other specified directories.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/shared-docs",
        "/Users/username/reference-projects"
      ]
    }
  }
}

Security consideration: Limit the directories granted access to the minimum necessary. Avoid granting access to the entire home directory (/Users/username); specify only the required subdirectories.

---

SQLite MCP (Database Queries)

The SQLite MCP server allows running queries directly against a local SQLite database.

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "/Users/username/projects/myapp/data/app.db"
      ]
    }
  }
}

Operations enabled by SQLite MCP:

• List tables and inspect schemas
• Run SELECT queries
• Aggregate and analyze data
• Verify data to validate behavior of code generated by Claude Code

---

Combined Configuration with Multiple MCP Servers

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/shared-docs"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

---

Combining MCP with Claude Code Skills and Agents

Calling MCP Tools from a Skill

Calling MCP tools from a Skill allows routine tasks to be defined as reusable, callable procedures.

Example skill file (.claude/commands/create-pr.md):

# Create a Pull Request

Follow these steps to create a Pull Request.

1. Run `git diff main` to review the changes.
2. Use the GitHub MCP server's `create_pull_request` tool to create the PR:
   - title: auto-generate from commit messages
   - body: describe the summary of changes, testing approach, and scope of impact
   - base: `main`
   - draft: false
3. Output the PR URL.

Least-Privilege Design: Granting Only Specific MCP Tools to an Agent

The principle of least privilege is a design policy that restricts an agent to only the minimum set of tools it needs. Giving an agent unrestricted access to all MCP tools creates a risk of unintended operations such as data deletion or sending information externally.

Example agent definition file (.claude/agents/data-analyst.md):

---
name: data-analyst
description: Data analysis agent. Only SQLite and Brave Search are available.
tools:
  - mcp__sqlite__query         # Only the SQLite MCP query tool is permitted
  - mcp__brave-search__search  # Only the Brave Search MCP search tool is permitted
  # GitHub MCP and Filesystem MCP are excluded
---

You are a data analysis expert.
Analyze data using the SQLite database and web search.
Do not modify files or perform any GitHub operations.

graph TD
  CC[Claude Code] --> |full MCP access| FULL[Full Access]
  CC --> |least privilege| AGENT[data-analyst agent]

  FULL --> MCP1[GitHub MCP]
  FULL --> MCP2[Filesystem MCP]
  FULL --> MCP3[SQLite MCP]
  FULL --> MCP4[Brave Search MCP]

  AGENT --> |allowed| MCP3
  AGENT --> |allowed| MCP4
  AGENT --> |denied| MCP1
  AGENT --> |denied| MCP2

---

Troubleshooting

Steps to Check When an MCP Server Fails to Start

1. Verify npx is available: Run npx --version to confirm npx is accessible
2. Verify the package name: Confirm the package name (e.g., @modelcontextprotocol/server-github) is correct
3. Verify environment variables: Confirm required environment variables (GITHUB_TOKEN, etc.) are set
4. Restart Claude Code: After updating settings.json, restart Claude Code
5. Check debug logs: Run /mcp in Claude Code to check the status of MCP servers

Common Errors and Resolutions

Error	Cause	Resolution
spawn npx ENOENT	npx not found	Reinstall Node.js or verify the version with nvm
GITHUB_PERSONAL_ACCESS_TOKEN is not set	Environment variable not set	Set with export GITHUB_TOKEN=... and restart the shell
Permission denied	No access rights to the specified path	Check filesystem permissions with ls -la
Connection refused	Remote MCP server is not running	Verify the server URL and port
Tool not found	MCP server is running but tool name is incorrect	Verify the server name in settings.json and the tool call name

Resolving Permission Errors

When a permission error occurs with the Filesystem MCP, check read/write access to the specified directory.

# Check directory permissions
ls -la /Users/username/shared-docs

# Grant permissions if missing (read/write/execute for owner)
chmod 755 /Users/username/shared-docs

If modifying permissions is inappropriate for security reasons, consider specifying a more appropriate directory or sharing files through an alternative method.

---

Summary

• MCP is a protocol that standardizes external tool integration for AI models, significantly extending Claude Code’s tool range
• Local and remote MCP servers are configured in the mcpServers section of settings.json
• Official MCP servers are available for GitHub, Filesystem, SQLite, and more — configuration requires only a few lines of JSON
• Calling MCP tools from a Skill allows routine tasks to be defined as reusable procedures
• Apply the principle of least privilege to agents, permitting only the minimum required MCP tools
• When an MCP server fails to start, check environment variables, the package name, and restart Claude Code in sequence

---

FAQ

Q: Where are MCP servers published and managed?

Official MCP servers are maintained in the modelcontextprotocol/servers GitHub repository. Many community-built servers are also available, distributed as npm packages.

Q: Is it possible to build a custom MCP server?

Yes. The MCP protocol is an open standard, and servers can be implemented in multiple languages including Python, TypeScript, and Go. Creating a custom server that connects Claude Code to an internal API or proprietary data source enables more advanced automation workflows.

Q: How should project-level and global settings.json be used?

.claude/settings.json (project level) is used for settings specific to that repository. ~/.claude/settings.json (global) is used for settings shared across all projects. A common pattern is to configure project-specific MCP servers (particular databases or APIs) at the project level, and frequently used MCPs such as Brave Search at the global level.

Q: Are there security risks when adding MCP servers?

Adding MCP servers grants Claude Code additional tools and permissions. It is important to use only servers from trusted sources. When configuring MCP servers that connect to external networks (GitHub, Slack, etc.), limiting the scope of the API keys provided to the minimum necessary is recommended.

---

See the references for the external specifications and background sources used on this page.[1][2][3]

References

1. Model Context Protocol official site
2. Official MCP server list (GitHub)
3. Anthropic Claude Code Documentation

---