Using MCP Servers in Claude Code

1. The integration problem MCP solves

Out of the box, Claude Code can read files, run shell commands, and search the web. That covers a huge range of development tasks. But real development happens inside a web of connected services: your issues are in Linear or Jira, your code is in GitHub, your data is in Postgres, your infrastructure is in AWS, your documentation is in Notion. Every time Claude Code needs to interact with one of these services, it has two options: use the shell to run a CLI tool, or use a generic web fetch to call an API. Both work, but neither is elegant or reliable at scale.

The Model Context Protocol (MCP) is the solution. MCP is an open standard, developed by Anthropic but now maintained by the broader AI ecosystem, that defines how AI agents connect to external tools and data sources. An MCP server is a small process that implements this standard for a specific service — GitHub, Postgres, Linear, Stripe, and hundreds of others — and exposes its functionality as a set of typed, named tools that Claude Code can call directly.

The result is a qualitative improvement. Instead of asking Claude Code to “run gh issue list --state=open --assignee=@me and parse the output”, you can simply say “what are my open Linear tickets?”. Instead of constructing a curl command to call the GitHub API, you can say “open a pull request for this branch”. The MCP layer handles the API authentication, the response parsing, and the error handling — leaving Claude Code free to use the results as context for the task at hand.

2. How MCP servers work

An MCP server is a process that runs locally on your machine (or, in some configurations, on a remote server) and communicates with Claude Code over a standardized protocol. From Claude Code’s perspective, an MCP server looks like an additional set of tools: it can call them the same way it calls its built-in tools, and the results come back in a consistent format.

Each MCP server exposes a set of named tools with typed parameters. The GitHub MCP server might expose tools like create_pull_request, list_issues, get_file_contents, and create_branch. The Postgres MCP server might expose execute_query, list_tables, and describe_table. When you tell Claude Code about a task that could benefit from one of these tools, it calls them as naturally as it calls bash or read_file.

Authentication credentials for each MCP server are configured once and stored securely — you do not need to paste API tokens into every prompt. The MCP server handles the credential management and makes authenticated calls on Claude Code’s behalf.

3. Adding an MCP server to Claude Code

MCP servers are configured in Claude Code’s settings file. The settings live at ~/.claude/settings.json for global configuration and .claude/settings.json (project root) for project-specific configuration.

To add an MCP server, use the claude mcp add command. For example, to add the official GitHub MCP server:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

This adds the server configuration to your settings file. The server will be started automatically when Claude Code launches. You can verify it was added successfully with:

claude mcp list

For servers that require authentication, the configuration includes an env block where you specify environment variable names (not values — the actual secrets stay in environment variables or a .env file):

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

4. Global vs. project-level scoping

MCP servers can be configured at two levels, following the same hierarchy as CLAUDE.md.

Global MCP servers are available in every Claude Code session, regardless of project. These are the right home for general-purpose tools: a GitHub server (you use GitHub everywhere), a general web search augmentation, or any tool that is equally useful across all your projects. Global servers are configured in ~/.claude/settings.json.

Project MCP servers are only available when Claude Code is running inside that project’s directory tree. These are the right home for project-specific services: the specific Postgres database for this project, the Linear workspace for this team, or a custom internal tool that only makes sense in this codebase context. Project servers are configured in .claude/settings.json at the project root.

5. High-value MCP servers for developers

The MCP ecosystem has hundreds of servers, but a small set delivers disproportionate value for most development workflows.

GitHub (@modelcontextprotocol/server-github) — creates and reviews pull requests, manages issues, reads file contents from any branch, lists repository information. Particularly valuable for multi-repo work where the relevant context lives in a different repository than the one you are editing.

Postgres (@modelcontextprotocol/server-postgres) — executes SQL queries, describes table schemas, lists available tables and views. Useful when building features that interact with the database: Claude Code can look up the actual schema rather than relying on ORM models that might be out of sync.

Filesystem (@modelcontextprotocol/server-filesystem) with restricted scope — gives Claude Code access to directories outside the current project. Useful when your frontend and backend live in separate repositories and you need Claude Code to read from both.

Linear (@linear/mcp) — reads and creates issues, searches the backlog, updates issue status. Lets Claude Code understand the ticket context for the feature it is implementing without you needing to paste the ticket description.

Brave Search / Tavily — augments Claude Code’s web search with higher-quality, more recent results. Useful when working with fast-moving ecosystems where training data is likely stale.

6. Context cost considerations

Each MCP server you enable adds overhead: the server must start, its tool descriptions must be loaded into the context window, and every tool call consumes tokens for both the request and the response. For a session working on a narrow task, loading five MCP servers “just in case” is context waste.

Practical approach: install the servers you regularly use, but be deliberate about which ones are global versus project-scoped. A database server that is irrelevant to a documentation task costs tokens for no benefit. Project-level scoping and keeping your global configuration lean are the main levers.

claude mcp add github -- npx -y @modelcontextprotocol/server-github

export GITHUB_TOKEN=ghp_your_token_here

claude mcp list

claude

List my 5 most recently updated GitHub repositories and tell me which ones have open pull requests.

cd ~/projects/your-app
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/your-db

Describe the schema of the users table and suggest any missing indexes based on the 
query patterns you can infer from the codebase's database calls.

git add .claude/settings.json
git commit -m "Add project MCP server configuration for Postgres"