Claude Code MCP Integration: A Practical Setup Guide

Who this is for: developers already using Claude Code who want it to read GitHub issues, click through a real browser, or query a live database instead of guessing from stale context. If you have typed "just check the PR comments" and watched Claude shrug, this is the fix.

Claude Code MCP integration is the difference between an assistant that only sees your local files and one that can open a browser tab, run a SQL query, or file a GitHub comment on your behalf. MCP (Model Context Protocol) is the open standard Anthropic shipped in late 2024 that lets any tool expose itself to any compatible client through one consistent interface, instead of every integration being a bespoke plugin. This guide walks through the actual config files, the three transport types, four servers worth installing today, and the permission model you need to not regret it later.

What MCP actually solves

Before MCP, every AI coding tool needed its own custom connector for GitHub, its own custom connector for databases, its own custom connector for browsers. Write once, use everywhere never happened, because "everywhere" kept changing its plugin API. MCP fixes this by defining a single JSON-RPC-based protocol: a server exposes tools, resources, and prompts; a client (Claude Code, Claude Desktop, or any other MCP-aware app) discovers and calls them. The server doesn't know or care which client is talking to it.

For Claude Code specifically, this means three concrete capabilities land in your terminal session:

• Tools - functions Claude can call, like create_pull_request or run_sql_query.
• Resources - readable context, like a file, a database schema, or a live log stream.
• Prompts - reusable prompt templates the server ships, which show up as slash-command-like shortcuts.

If you already run Claude Code subagents or custom slash commands, MCP servers are the natural next layer: subagents decide what to do, slash commands standardize how you ask, and MCP servers give both of those actual hands to act with outside your local filesystem.

The three transports, and which one to pick

MCP servers connect over one of three transports. Getting this wrong is the single most common reason a server "installs" but never actually talks to Claude Code.

Tip: stdio is the right default for anything running on your own machine. Only reach for SSE or Streamable HTTP when the server is genuinely a remote service you're calling over the network - a hosted Postgres proxy, a SaaS API wrapper, that kind of thing. Adding a network hop for a tool that could just run locally is pure latency tax.

Configuring servers: project vs user vs enterprise scope

Claude Code reads MCP server definitions from .mcp.json files at three levels, and they layer on top of each other:

1. User scope - ~/.claude.json (or the equivalent user config path) - servers available in every project you open.
2. Project scope - .mcp.json at the repo root - servers specific to this codebase, checked into git so teammates get them automatically.
3. Enterprise/managed scope - pushed by an admin policy, cannot be overridden locally - used for org-wide compliance tools.

A minimal project-scoped .mcp.json looks like this:

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

Note the ${GITHUB_TOKEN} interpolation - never hardcode a secret directly into a file you're about to commit. Claude Code expands environment variables at launch time, so the token lives in your shell profile or .env, not in git history.

Once the file exists, run claude mcp list to confirm Claude Code sees the servers, and /mcp inside a session to check live connection status. If a server shows as failed, it's almost always one of: wrong command path, missing npm package cache (first run downloads it, which can time out on a slow connection), or a missing env var.

Adding a server via CLI instead of hand-editing JSON

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

This writes the same .mcp.json entry for you, which is less error-prone than hand-editing quotes and commas at 11pm.

Four servers worth installing

GitHub

The official @modelcontextprotocol/server-github (or GitHub's own hosted MCP server, which as of 2026 supports OAuth so you don't manage a PAT at all) gives Claude tools like create_issue, list_pull_requests, add_comment, and merge_pull_request. In practice this collapses a five-tab workflow - check PR, read comments, check CI status, comment back, merge - into one conversational turn. The main gotcha: scope your token narrowly. A fine-grained PAT limited to the specific repos you work in, not a classic token with full org access.

Playwright

Microsoft's @playwright/mcp gives Claude a real, controllable browser: navigate, click, fill forms, take screenshots, read the accessibility tree. This is the difference between "trust me, the button probably works" and Claude actually clicking it and reporting what happened. It pairs extremely well with visual regression checks and with debugging flaky end-to-end tests - Claude can run the failing test's steps manually and narrate exactly where the DOM diverges from expectation.

Postgres

The Postgres MCP server exposes schema introspection and read queries as tools. This is genuinely useful for debugging ("show me the last 20 rows where status is failed") and for writing migrations against real schema instead of a stale schema.sql file. It is also the server where permission discipline matters most - see the security section below before you point it at production.

Filesystem (built-in, worth mentioning for contrast)

Claude Code already has native file read/write - you don't need an MCP server for this. The lesson here is: don't reach for MCP just because it exists. If Claude Code's built-in tools already cover the job, adding an MCP server is extra surface area for no gain. MCP earns its keep exactly where Claude needs to reach outside its own process - a browser, an external API, a database connection.

Permissions and security: the part people skip

MCP tools run with whatever privileges their underlying credentials have, and Claude Code's permission system treats each tool call as something to gate, not something to trust by default.

• Read vs write tools get different defaults. list_issues is safer to auto-approve than merge_pull_request. Use .claude/settings.json permission rules to allow read-only MCP tools and require confirmation on anything mutating.
• Scope credentials to the minimum. A Postgres MCP server pointed at a read-replica with a SELECT-only role is a fundamentally different risk profile than one pointed at your primary database with a superuser password. Do the former.
• Treat MCP server code as third-party dependency code, because it is. npx -y pulls whatever is published under that package name at that moment. Pin versions in production-facing setups instead of trailing @latest.
• Audit what a new server can see before adding it project-wide. A server with filesystem access, run inside a monorepo, can read .env files sitting three directories away from where you think it's scoped.

Warning: a compromised or malicious MCP server is functionally equivalent to running an unreviewed npm package with your GitHub token and database credentials in its environment. Treat installation the same way you'd treat npm install from a package you've never audited - check the source, check download counts, check who maintains it.

This overlaps heavily with what we cover in Claude Code permissions and safety - if you haven't set up a .claude/settings.json permission policy yet, do that before adding your third or fourth MCP server, not after something goes wrong.

Debugging a server that won't connect

When /mcp shows a server as disconnected or erroring, work through this order:

1. Run the command manually. Copy the exact command + args from .mcp.json and run it in your terminal directly. If it errors there, the problem is the server, not Claude Code.
2. Check env var expansion. Add a temporary echo $GITHUB_TOKEN (or the Windows/PowerShell equivalent) to confirm the variable is actually set in the shell Claude Code launches from - a variable set in one terminal profile doesn't always carry into another.
3. Check for stale npm cache. npx -y sometimes serves a cached broken version. Clear with npx clear-npx-cache or bump to an explicit version tag.
4. Look at stdout/stderr from the subprocess. Claude Code surfaces some of this in verbose mode (claude --mcp-debug or the equivalent debug flag in your installed version) - read the actual error text before guessing.
5. Confirm scope isn't being overridden. A user-scope server and a project-scope server with the same name will conflict; project scope wins, which surprises people who forgot they added it globally first.

Most "MCP is broken" reports turn out to be step 1 or step 2. The protocol layer is rarely the actual bug.

MCP vs building your own tool integration

It's worth being honest about when MCP is overkill. If you need Claude to call exactly one internal API for one project, writing that as a direct API call inside a script - or exposing it via Claude Agent SDK tool definitions - can be less overhead than standing up a full MCP server. MCP earns its complexity budget when:

• You want the same integration available across multiple clients (Claude Code, Claude Desktop, other MCP-compatible tools).
• The tool is something you'll reuse across many projects, not a one-off.
• You want your team to share a config file (.mcp.json in git) instead of everyone hand-rolling their own script.

If none of those apply, a simpler direct integration is genuinely the better call - see our broader comparison in MCP servers explained for the conceptual side of this trade-off.

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 - GitHub, databases, browsers, and more - through a consistent protocol instead of custom one-off integrations. You configure servers in an .mcp.json file, and Claude Code discovers their tools automatically at session start.

How do I add an MCP server to Claude Code?

Either hand-edit .mcp.json at the project or user level with a command, args, and optional env block, or run claude mcp add <name> --scope project -- <command> from the CLI, which writes the file for you. Run claude mcp list and /mcp inside a session to verify the server connected.

Is it safe to give Claude Code database access via MCP?

It's safe if you scope the credentials tightly - a read-only role on a non-production database is a reasonable starting point. Giving an MCP server superuser credentials on production is the same risk as giving any unreviewed script that access, and should be treated with the same caution described in our permissions and safety guide.

What's the difference between stdio and SSE transports?

stdio spawns the MCP server as a local subprocess and talks over standard input/output - lowest latency, best for tools running on your own machine. SSE (and the newer Streamable HTTP) connect to a remote server over HTTP, which adds network latency but is necessary when the tool genuinely lives elsewhere, like a hosted SaaS API.

Can I use the GitHub MCP server without a personal access token?

As of 2026, GitHub's own hosted MCP server supports OAuth-based auth for some setups, removing the need to manage a PAT yourself. If you're using the community @modelcontextprotocol/server-github package, you'll still need a fine-grained PAT scoped to the specific repos you work in.

Why does my MCP server show as connected but tools don't appear?

This usually means the server initialized but failed the tool-discovery handshake - check the server's own logs for a schema validation error, and confirm you're running a version of the server compatible with your Claude Code client version, since MCP's tool schema format has evolved across protocol revisions.

Get help wiring this up

If you want a second pair of eyes on your MCP config, permission policy, or which servers actually make sense for your stack, we do free 30-minute calls to talk through it - book one through the contact form or message us directly on WhatsApp.

Sources

• Model Context Protocol specification
• Anthropic Claude Code documentation
• GitHub MCP server
• Playwright MCP server
• Anthropic MCP announcement