MCP Setup: Connecting External Tools

You are triaging a production bug. You need to check the Sentry error, look at the related GitHub PR, query the database for affected users, and update the Jira ticket — four different browser tabs, four different contexts, constant copy-pasting between tools. With MCP servers connected, you can do all of this from a single Claude Code session: “Check the latest Sentry errors, find the PR that introduced the issue, query how many users are affected, and create a fix.”

MCP (Model Context Protocol) is the open standard that lets Claude Code connect to external tools and data sources. This guide gets you from zero to your first connected MCP server in 15 minutes.

What You’ll Walk Away With

At least one MCP server connected and working
Understanding of remote HTTP servers versus local stdio servers
Knowledge of user, project, and local scopes for MCP configuration
Practical examples for the most popular MCP servers

How MCP Works in Claude Code

MCP servers give Claude additional tools beyond its built-in file operations and bash commands. When you connect a GitHub MCP server, Claude can list PRs, create issues, and review code. When you connect Sentry, Claude can search errors and analyze stack traces. The tools are available to Claude automatically — you just ask for what you want in natural language.

There are two types of MCP servers:

Remote HTTP servers — Cloud-hosted services you connect to via URL. Most popular services (GitHub, Sentry, Slack, Linear, Notion) offer these. One command to add, no local installation needed.
Local stdio servers — Programs that run on your machine. Use these for databases, file system tools, or custom integrations.

Adding Your First MCP Server

Remote HTTP Server (Recommended Start)

The easiest server to set up is a remote HTTP server. Let’s connect GitHub:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Then inside a Claude Code session, authenticate:

/mcp
# Select "Authenticate" for GitHub, follow the browser flow

That’s it. You can now ask Claude to interact with GitHub:

Show me all open PRs assigned to me in this repository.

Other Popular Remote Servers

# Sentry - error monitoring
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Linear - issue tracking
claude mcp add --transport http linear https://mcp.linear.app/mcp

# Slack - messaging
claude mcp add slack --transport http https://mcp.slack.com/mcp

# Notion - documentation
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Figma - design files
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Stripe - payments
claude mcp add --transport http stripe https://mcp.stripe.com

# Atlassian (Jira/Confluence)
claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp

# Vercel - deployments
claude mcp add --transport http vercel https://mcp.vercel.com

Each server requires authentication via /mcp after adding. OAuth tokens are stored securely and refreshed automatically.

Copy-paste prompt after connecting GitHub + Sentry:

Check Sentry for the most recent unresolved errors in the last
24 hours. For each error, find the related code in this repository
and suggest a fix. If there is a recent PR that may have introduced
the error, identify it.

Local Stdio Server (Database Example)

For tools that need direct access to your infrastructure, use local servers:

# PostgreSQL database access
claude mcp add --transport stdio db -- \
  npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:password@localhost:5432/myapp"

Now Claude can query your database in natural language:

How many users signed up in the last 7 days? Break it down by day.

MCP Scopes: Where Servers Are Configured

MCP servers can be added at three scopes:

Scope	Flag	Stored In	Shared?
Local (default)	`--scope local`	`~/.claude.json` (per-project)	No
Project	`--scope project`	`.mcp.json` in repo root	Yes (committed)
User	`--scope user`	`~/.claude.json` (global)	No

Use local scope (default) for servers with your personal credentials, like your Sentry account.

Use project scope for servers the whole team needs:

claude mcp add --transport http linear --scope project https://mcp.linear.app/mcp

This creates or updates .mcp.json in your project root, which you commit to git. Team members are prompted to approve the server when they first open the project.

Use user scope for servers you want across all projects:

claude mcp add --transport http slack --scope user https://mcp.slack.com/mcp

Managing MCP Servers

# List all configured servers
claude mcp list

# Check details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# Check server status (inside a Claude Code session)
/mcp

Project-Scoped MCP with .mcp.json

For team-shared MCP configuration, the .mcp.json file at your project root defines servers that every team member should have:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
      "env": {}
    }
  }
}

Note the ${DATABASE_URL} environment variable expansion. This lets each developer use their own database URL without hardcoding credentials in the shared config.

Copy-paste prompt to set up MCP for your team:

Read our .mcp.json file and verify all configured MCP servers are
running correctly. For any server that fails to connect, explain
what might be wrong and how to fix it. Then suggest additional MCP
servers that would be useful based on the tools and services this
project uses.

Environment Variable Expansion

.mcp.json supports environment variables in commands, args, URLs, and headers:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

The ${VAR:-default} syntax provides a fallback value when the variable is not set.

MCP Tool Search

When you have many MCP servers with many tools, the tool definitions can consume significant context. Claude Code automatically enables MCP Tool Search when tool descriptions exceed 10% of the context window. Instead of loading all tools upfront, Claude discovers and loads tools on demand.

You can control this behavior:

# Always enable tool search
ENABLE_TOOL_SEARCH=true claude

# Disable tool search (load all tools upfront)
ENABLE_TOOL_SEARCH=false claude

# Custom threshold (e.g., 5% of context)
ENABLE_TOOL_SEARCH=auto:5 claude

When This Breaks

“Connection closed” for local stdio servers on Windows — Windows cannot directly execute npx. Wrap the command with cmd /c:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Server added but tools do not appear — Run /mcp inside Claude Code to check server status. If the server shows as disconnected, try removing and re-adding it. Check that the URL is correct and the service is online.

OAuth authentication fails — Use /mcp to re-authenticate. If you see “does not support dynamic client registration,” the server requires pre-configured OAuth credentials with --client-id and --client-secret.

MCP output exceeds token limit — For servers that return large results (database queries, log dumps), increase the limit: export MAX_MCP_OUTPUT_TOKENS=50000. The default is 25,000 tokens.

Project .mcp.json servers not loading — Claude Code prompts for approval before using project-scoped servers. If you declined, reset with claude mcp reset-project-choices.

What’s Next

With MCP servers connected, you have everything you need to build your first feature end to end with Claude Code.

Development Workflow Build your first feature with Claude Code

Version Control Git integration and branch management