Claude Code MCP Guide — Connect to Any Tool (2026)

by

Right now, Claude Code knows your code. It can read your files, run your tests, fix your bugs, and navigate your entire codebase. But the moment you need it to check a GitHub issue, query a database, post to Slack, or look up a Notion doc — it hits a wall. Not because it’s not capable, but because it has no connection to those systems. It’s a brilliant developer who has never been given access to your tools.

MCP — the Model Context Protocol — is what gives Claude Code that access. It’s an open standard that connects Claude Code to any external tool or data source through a consistent interface. GitHub, Postgres, Slack, Notion, your internal APIs, your monitoring stack — all of it becomes directly callable from inside a Claude Code session. When MCP is set up well, Claude doesn’t just help you write code. It reads the GitHub issue you’re working on, queries the production data you need to understand the bug, commits the fix, and posts a summary to the team Slack channel. All from one session. This guide shows you exactly how that works, from zero.

## 📋 TL;DR

– MCP (Model Context Protocol) is an open standard that lets Claude Code call external tools and data sources — GitHub, databases, Slack, Notion, and thousands more.
– Anthropic launched MCP in November 2024, donated it to the Linux Foundation in December 2025, and by mid-2026 there are over 2,300 public MCP servers available.
– Each MCP server exposes three types of capabilities: Tools (functions Claude can call), Resources (data it can read), and Prompts (templates it can invoke).
– Adding a server is one command: claude mcp add . Claude discovers the new tools automatically on the next session.
– MCP servers operate at three scopes: local (your machine only), project (shared via .mcp.json in Git), and user (all your projects).
– Every server you add increases Claude’s context overhead at startup — don’t add servers you don’t regularly use.
– MCP servers run with real credentials and can take real actions. Treat them like you would any other tool with production access: use scoped tokens, minimal permissions, and trusted sources only.

Table of Contents

What Is MCP — The USB Port Analogy

Before MCP, connecting an AI tool to an external service required custom integration code. Want Claude to read your Jira tickets? Someone had to write a Jira-specific connector. Want it to query your Postgres database? A Postgres-specific integration. Every new combination of AI tool and external service was a separate engineering project.

MCP is Anthropic’s open standard for connecting language models to external tools and data sources. Think of it as USB for AI: one protocol, many tools, many clients. Before MCP, every AI client had to build a custom integration for every tool. With MCP, you write the integration once as a server, and any MCP-compliant client can call it.

The USB analogy is the right one. Before USB, every peripheral — keyboards, mice, printers, cameras — needed a different port. Connecting a new device meant checking compatibility, installing specific drivers, hoping it worked. USB standardized the connection, so any device works with any port. MCP does the same thing for AI tools and external services: one standard connection interface, any tool on one side, any AI client on the other.

That protocol is now maintained by the Linux Foundation (not solely by Anthropic), making it genuinely open infrastructure. Cursor, VS Code, ChatGPT, and dozens of other AI tools all support MCP alongside Claude Code. A GitHub MCP server you configure for Claude Code will also work with any other MCP-compatible client — no reconfiguration needed.

For Claude Code specifically, MCP is what turns it from a great coding tool into a connected workspace. A session with the right MCP servers is one where Claude can read the GitHub issue you’re implementing, check the database schema to understand the data model, run a test query against a staging database, commit the fix, and update the Notion task — without you switching windows or copy-pasting information between tools.

Diagram showing Claude Code (centre) connected via MCP to five external tools: GitHub, Postgres, Slack, Notion, and a custom API — illustrating the hub-and-spoke architecture where MCP is the single connection standard

[What is MCP? (Model Context Protocol Explained)]

What an MCP Server Actually Does

An MCP server is a process — a running program — that sits between Claude Code and an external service. It implements the MCP protocol on one side and talks to the external service on the other. When Claude wants to search GitHub issues, it calls a function on the GitHub MCP server. The server makes the GitHub API call, formats the response, and returns the result to Claude.

MCP servers expose three types of capabilities — called primitives:

Tools are functions Claude can call — like search_repos, create_issue, query_database, or send_message. These are the most common and most useful primitive. When you ask Claude to “check if there’s an open issue for this bug,” it calls a tool on the GitHub MCP server. Tools can take parameters, execute logic, and return results. They’re the actions Claude takes in external systems.

Resources are pieces of data Claude can read — like file://README.md, db://users/123, or notion://page/abc. Resources are read-only. They give Claude access to external data without exposing callable functions. A database MCP server might expose individual tables as resources, letting Claude read the schema and sample data without being able to run arbitrary SQL queries.

Prompts are pre-written instruction templates that users can invoke by name. Less common in practice, but useful for standardizing how Claude approaches specific workflows — a “create PR description” prompt that structures the output exactly how your team expects it.

When you add an MCP server to Claude Code, it starts at the beginning of your session and announces its capabilities — all the tools, resources, and prompts it offers. Claude receives that list and can use any of them as naturally as it uses its built-in tools (Read, Write, Edit, Bash, Glob, Grep). From Claude’s perspective, a GitHub MCP tool works exactly the same way as any other tool call — it just reaches further.

💡 Pro Tip: A short tool list matters more than most people expect. The model has to consider every tool on every turn. A bloated tool list slows the agent down and increases the chance it picks the wrong tool. Don’t add every interesting MCP server you find. Add the ones you’ll actually use in this project, in this session. A tight, focused tool set produces better and faster results than a comprehensive one.

[What is MCP? (Model Context Protocol Explained)]

How to Add Your First MCP Server

Adding an MCP server to Claude Code is a single command. Here’s the complete process from scratch:

Step 1: Find the server’s installation command

Most MCP servers are published as npm packages. The server’s README or the MCP registry listing (more on that below) will show you the exact installation command. For the official GitHub MCP server, it looks like this:


claude mcp add github-mcp \
  --command="npx" \
  --args="-y,@modelcontextprotocol/server-github" \
  --env="GITHUB_TOKEN=your-token-here"

This tells Claude Code: “There’s a server called github-mcp. To start it, run npx -y @modelcontextprotocol/server-github. Pass it this environment variable.”

Step 2: Run the command

Open your terminal and run the claude mcp add command. Claude Code registers the server configuration locally. No restart needed for the configuration to be saved.

Step 3: Start a new session

MCP servers are loaded at the start of each session. Open a new Claude Code session (or run claude in a new terminal) and the server will start automatically. You can verify it’s connected by running /mcp inside the session — this shows all connected servers and their status.

Step 4: Use the tools

That’s it. The server’s tools are now available to Claude. You can ask Claude directly: “Search for open issues mentioning ‘login’ in my-repo.” Claude will identify the right GitHub tool to call and use it.

The interactive wizard (alternative)

If you prefer a guided setup, run claude mcp add without any arguments. This launches an interactive wizard in the terminal that walks you through server name, command, arguments, and environment variables step by step.

Where credentials go

Most MCP servers need API keys or tokens to authenticate with the external service. These go in the --env flag when running claude mcp add. Claude Code stores them in your local configuration — they never touch your project files or get committed to Git.

Always use scoped tokens with the minimum permissions the server actually needs. For the GitHub MCP server, a token with only repo:read access is safer than a full-access personal access token. If the token is ever leaked (via a log, a screen share, a prompt injection), the damage is bounded.

How to Add an MCP Server to Claude Code

Terminal showing the claude mcp add command being run, then a new session starting with /mcp showing the connected server and its available tools listed

MCP Scopes — Local, Project, and User

One of the most confusing parts of MCP setup is the scope system. Understanding it prevents the most common “why can’t Claude see this server?” problems.

The three scopes are local, project, and user. Local scope lives in ~/.claude.json, keyed by the absolute path of the current project. It’s the default when you run claude mcp add without a --scope flag. It applies only when you’re working in that folder, and nothing in it gets committed.

Here’s how each scope works in practice:

Local scope (default) — The server configuration is stored in ~/.claude.json keyed to your current project directory. It’s available only in that directory, only on your machine, and never shared with anyone. Use this for personal API tokens, one-off experiments, and any server configuration that contains credentials you don’t want in your repository.


# Default — local scope
claude mcp add my-server --command=npx --args="-y,my-server"

Project scope — The server configuration is stored in .mcp.json at the root of your project repository and is designed to be committed to Git. Every developer who clones the repository gets the same MCP servers when they use Claude Code. This is the right scope for team-shared tools: your staging database server, your company’s internal APIs, a shared monitoring integration.


# Project scope — stored in .mcp.json, commit to Git
claude mcp add my-server --scope project --command=npx --args="-y,my-server"

When a teammate pulls your .mcp.json, Claude Code will ask them to approve the new servers before using them — a security guardrail that protects against a malicious server being slipped into a repository.

User scope — Available across all your projects on this machine. Stored in ~/.claude.json at the user level (not tied to a specific project path). Use this for personal productivity servers that make sense everywhere you work — a Notion server for reading your notes, a calendar integration, tools that belong to you rather than any specific project.


# User scope — available in all projects
claude mcp add my-server --scope user --command=npx --args="-y,my-server"

Priority when scopes conflict: Local wins over project, which wins over user. If the same server is configured at multiple scopes, the most specific one takes effect.

💡 Pro Tip: For team projects, commit a project-scope .mcp.json with placeholder environment variable names and document which secrets developers need to fill in themselves. This way the team shares the server configuration (which tools to use, which command to run) while each developer supplies their own credentials locally. Never commit actual API keys or tokens in .mcp.json.

[MCP Scopes — Local vs Project vs User]

The MCP Registry — Finding Servers to Install

By mid-2026, over 2,300 public MCP servers are available. You don’t need to build your own server for the vast majority of common integrations — someone has almost certainly already built it.

The main places to find servers:

Anthropic’s MCP registry (mcp.so and the in-app registry accessible via /mcp add inside a Claude Code session) — The curated official directory. Searchable by category. Each listing shows the installation command, required credentials, available tools, and community ratings.

GitHub — Most MCP servers are open source. The @modelcontextprotocol GitHub organization maintains official reference servers for GitHub, filesystem access, web fetching, databases, and a growing list of integrations. These are the most reliable starting points.

The community — npm, GitHub topics, and community databases like mcp.directory list community-built servers. Quality varies. Always review what a community server does before installing it — especially what permissions it requests and what network access it has.

Inside a Claude Code session, you can explore and install servers through the /mcp command. /mcp list shows your currently connected servers. /mcp add launches an interactive search and installation flow. /mcp remove removes a server.

When evaluating a server to install, check:

  • Who maintains it** — Official Anthropic servers or well-known company servers (Notion, GitHub, etc.) are safer than anonymous community packages
  • What tools it exposes** — Read the list. Do these tools have write access? Can they make network requests? Can they read files outside your project?
  • What credentials it needs** — Does it ask for more permissions than it should need?
  • When it was last updated** — An unmaintained server may have security vulnerabilities or broken integrations

[The MCP Registry — Finding & Installing Servers]

Top 10 MCP Servers Every Developer Should Install

Practical MCP Setups — GitHub, Database, Slack, Notion

These are the four most commonly installed MCP servers for developers. Here’s what each one does and why it changes your workflow.

GitHub MCP

Gives Claude Code direct access to your GitHub repositories — issues, pull requests, commits, code search, and more. This is the most immediately useful server for most developers.


claude mcp add github-mcp \
  --command="npx" \
  --args="-y,@modelcontextprotocol/server-github" \
  --env="GITHUB_TOKEN=ghp_your_token_here"

What changes: instead of copying an issue number into Claude and pasting context manually, you just say “implement issue #247.” Claude reads the issue, understands the acceptance criteria, and starts working. It can also check for related issues, review PR comments, and create new issues when it discovers bugs.

Use a fine-grained personal access token scoped to the specific repositories you work on, with only the permissions you need (read issues and PRs, write pull requests if you want Claude to create them).

Database MCP (PostgreSQL / SQLite)

Gives Claude Code the ability to query your database — inspect the schema, run select queries, understand the data. Most database MCP servers are configured as read-only by default.


claude mcp add postgres-mcp \
  --scope project \
  --command="npx" \
  --args="-y,@modelcontextprotocol/server-postgres" \
  --env="DATABASE_URL=postgresql://user:password@localhost:5432/mydb"

What changes: instead of asking Claude to “guess” what your data looks like, it can actually read your schema and run sample queries. “Why is this query slow?” becomes a real analysis Claude can perform against actual data, not a theoretical discussion. Use project scope so the database configuration is shared with your team.

Security note: Always connect Claude to a read-only database user or a staging database — never production with write access. Treat it like giving a new contractor access to your data.

Slack MCP

Gives Claude the ability to read channels and post messages to your Slack workspace.


claude mcp add slack-mcp \
  --scope user \
  --command="npx" \
  --args="-y,@modelcontextprotocol/server-slack" \
  --env="SLACK_TOKEN=xoxb-your-bot-token"

What changes: Claude can post deployment summaries, bug reports, and status updates directly to the right channels without you copy-pasting anything. It can also read recent channel history if you want context about ongoing discussions. Use a bot token scoped to only the channels it needs.

Notion MCP

Gives Claude read and write access to your Notion workspace — pages, databases, and blocks.


claude mcp add notion-mcp \
  --scope user \
  --command="npx" \
  --args="-y,@modelcontextprotocol/server-notion" \
  --env="NOTION_TOKEN=secret_your_integration_token"

What changes: Claude can check your project documentation, update task status, and create new notes directly in Notion. Useful for teams that use Notion as a source of truth — Claude can read the spec before implementing a feature, not just the code.

[Claude Code + GitHub MCP]

[Claude Code + Database MCP]

[Claude Code + Slack MCP]

[Claude Code + Notion MCP]

MCP Security — What Beginners Often Miss

MCP servers are one of the most powerful features in Claude Code. They’re also the surface with the most security implications. Most beginners don’t think about this until something goes wrong. Here’s what to know upfront.

MCP servers run as subprocesses with your credentials. When Claude calls a GitHub MCP tool to create a pull request, that action happens with your GitHub token’s permissions. If that token has write access to all your repositories, Claude can create PRs in all of them. Principle of least privilege isn’t just good advice here — it’s protection against mistakes, not just malicious use. A Claude misunderstanding can have real consequences if the permissions are too broad.

Community MCP servers require scrutiny. Top MCP risks in production include prompt injection from untrusted content, data exfiltration via tool calls, npm supply chain attacks, and excessive permissions. Mitigations: pin MCP versions, disable network access when possible, audit the source code of community MCPs before installing. Before installing any community-built server, look at the source code. It doesn’t have to be a deep audit — check what it does with your credentials, what network calls it makes, and whether the package has been recently updated. Unmaintained packages are a supply chain risk.

Watch your context budget. A Supabase + GitHub + Linear stack of 81 tools consumed over 20,000 tokens before the user typed a single character — about 16% of a 128k context window. Every MCP server you add loads its tool schemas into Claude’s context at the start of every session. Adding ten servers doesn’t make Claude ten times more capable — it can make it slower and more prone to tool selection errors. Add servers only for tools you actually use in your current project.

Project .mcp.json files need review. When you pull a repository that contains .mcp.json, Claude Code will ask you to approve the listed servers. Don’t auto-approve without reading what they are. A malicious .mcp.json in a repository could point to a server designed to exfiltrate your credentials or modify your files in unintended ways.

Use separate credentials per context. Your personal GitHub token and your company’s CI token are different things. Don’t reuse credentials across contexts where the blast radius of a leak differs significantly.

[MCP Security Guide]

[MCP Troubleshooting — Common Errors]

Common Beginner Mistakes and How to Fix Them

Mistake 1: Adding too many MCP servers at once

The problem: You install a dozen interesting MCP servers in your first week. Claude starts responding slower, occasionally picks the wrong tool, and your context window fills up before you’ve typed much. You assume Claude Code is getting worse.

The fix: Every MCP server adds its tool list to Claude’s startup context. More tools mean a larger initial context load and more decisions Claude has to make on each turn. Start with two or three servers that address your actual daily workflow. Add more only when you hit a specific limitation. The right number of MCP servers for most developers is 3–5, not 15.

Mistake 2: Committing credentials to .mcp.json

The problem: You add a project-scoped MCP server with your API token in the configuration, commit .mcp.json to Git, and push. Your API token is now in your repository’s history — and potentially exposed if the repo is public or gets cloned broadly.

The fix: Commit a project-scope .mcp.json with placeholder environment variable names and document which secrets developers need to fill in themselves. Never put actual credentials in any file that gets committed. Use environment variable placeholders in .mcp.json (DATABASE_URL=${DATABASE_URL}) and have each developer set those variables in their local environment.

Mistake 3: Not running /mcp to verify the connection

The problem: You run claude mcp add and assume everything works. In your next session, Claude doesn’t seem to have access to the tools you expected. You don’t know whether the server failed to start, the credentials are wrong, or the tools aren’t being discovered.

The fix: After starting a new session with a newly added server, run /mcp immediately. This shows you every registered server, its connection status (connected / error / not started), and the tools it’s exposing. If a server shows an error, the error message usually tells you exactly what’s wrong — missing environment variable, wrong command path, authentication failure.

Mistake 4: Using full-access credentials instead of scoped tokens

The problem: You use your personal GitHub access token (full access to all your repos, including private ones) for the GitHub MCP server. This means Claude Code — and any prompt injection that might influence its tool calls — has broad access to everything.

The fix: Create a fine-grained personal access token scoped to exactly the repositories you’re working on and exactly the permissions the MCP server needs. For reading issues and creating PRs, you don’t need admin access or write access to repository settings. Spend five minutes creating the right-scoped token. The habit pays off.

Mistake 5: Not resetting project approval choices after .mcp.json changes

The problem: Your team updates .mcp.json to add a new server. You pull the changes, but Claude Code doesn’t prompt you to approve the new server — it silently uses your old approval state, and the new server doesn’t appear in your session.

The fix: Run claude mcp reset-project-choices after pulling any .mcp.json changes from your repository. This clears Claude Code’s memory of which project servers you’ve approved, triggering the approval prompt fresh on your next session so you can review and approve the updated server list.

Quick Reference Cheatsheet

**Topic** **The answer**
What is MCP? Open standard for connecting Claude Code to external tools and data sources
Three MCP primitives Tools (callable functions), Resources (readable data), Prompts (templates)
Add a server `claude mcp add –command= –args= –env=`
Add via interactive wizard `claude mcp add` (no arguments — launches guided setup)
Check connected servers `/mcp` inside a session
List servers via CLI `claude mcp list`
Remove a server `claude mcp remove `
Local scope (default) Your machine only, stored in `~/.claude.json` per project path
Project scope `.mcp.json` in repo root — committed to Git, shared with team
User scope All your projects on this machine, stored in `~/.claude.json` globally
Add project-scoped server `claude mcp add –scope project –command=…`
Add user-scoped server `claude mcp add –scope user –command=…`
Priority when scopes conflict Local > Project > User
Find servers to install MCP registry at mcp.so, `/mcp add` inside a session, or GitHub
Credential best practice Scoped tokens with minimum permissions; never commit tokens to Git
After pulling `.mcp.json` changes Run `claude mcp reset-project-choices` to re-trigger approval prompts
Context cost of MCP Each server’s tool schemas load at session start — keep your server count lean
Security check before installing Review source code, verify publisher, check what permissions are requested
GitHub MCP base command `npx -y @modelcontextprotocol/server-github`
Postgres MCP base command `npx -y @modelcontextprotocol/server-postgres`

What to Learn Next

MCP has depth at every level. Here’s the full path through the cluster, from foundations to advanced use:

Understand the foundations:

  • [What is MCP? (Model Context Protocol Explained)] — A focused conceptual introduction to what MCP is, how it works, and why it exists.

Get connected:

  • How to Add an MCP Server to Claude Code — Step-by-step walkthrough for the complete installation process, including authentication flows and verification.
  • [The MCP Registry — Finding & Installing Servers] — How to search the registry, evaluate servers before installing, and navigate the in-session /mcp add interface.
  • [MCP Scopes — Local vs Project vs User] — Deep dive on the three configuration locations, when to use each, and how to set up team sharing without committing credentials.

Popular integrations:

  • [Claude Code + GitHub MCP] — Full setup and usage guide for the GitHub integration, with token scoping recommendations and workflow examples.
  • [Claude Code + Database MCP] — Connecting Claude to PostgreSQL, SQLite, and other databases, with read-only safety patterns.
  • [Claude Code + Slack MCP] — Setting up and using the Slack integration for automated posting and channel reading.
  • [Claude Code + Notion MCP] — Reading and writing to Notion from Claude Code sessions.

Going further:

  • Top 10 MCP Servers Every Developer Should Install — Curated list of the highest-value servers for everyday development workflows, with quick install commands.
  • [Building Your Own MCP Server] — How to build a custom MCP server to expose your internal tools or proprietary APIs to Claude Code.

Staying safe:

  • [MCP Security Guide] — Threat models, credential handling, token scoping, prompt injection risks, and the security checklist every developer should work through.
  • [MCP Troubleshooting — Common Errors] — Diagnosis guide for the most common MCP setup failures: authentication errors, server not found, tools not appearing, and connection timeouts.

Key Takeaways

  • MCP is the standard that connects Claude Code to the world outside your codebase.** It’s what lets Claude read GitHub issues, query databases, post to Slack, and interact with any external service — all through a single consistent interface without custom integration code per tool.
  • Three primitives power every MCP server:** Tools (functions Claude can call, like search_issues or run_query), Resources (data it can read, like database tables or API responses), and Prompts (templates users can invoke by name). Tools are the most common and most useful.
  • Adding a server is one command.** claude mcp add --command= --args= --env= registers a server. New tools appear automatically in the next session. Verify with /mcp inside the session.
  • Scope controls who gets the server and where credentials live.** Local scope (default) is for your machine only — perfect for personal credentials. Project scope (.mcp.json in Git) shares the server configuration with your team. User scope makes a server available in all your projects. Never commit actual credentials to .mcp.json.
  • Fewer servers, better results.** Every MCP server adds tool schemas to your startup context. A bloated tool list slows Claude down and makes tool selection less accurate. Start with 2–3 servers that solve real daily frictions. Add more only when you hit specific limitations. Quality over quantity.

Last updated: July 2026. The MCP ecosystem moves quickly — check Anthropic’s official MCP documentation at modelcontextprotocol.io and code.claude.com/docs for the latest server recommendations and configuration options.