Claude Code MCP: Connect External Tools and Data Sources

Key Takeaways#

• MCP (Model Context Protocol) is an open standard that lets Claude Code connect to external data sources and tools — databases, browsers, APIs, and custom internal services.
• You can configure MCP servers three ways: CLI commands, settings.json, or the Agent SDK — pick whichever fits your workflow.
• Popular servers like Playwright, Filesystem, Memory, and GitHub are one npx command away from being productive.
• OAuth and authentication are first-class: MCP supports custom OAuth discovery (RFC 9728) and passes AI_AGENT env vars for subprocess attribution.
• Troubleshooting is straightforward — use /mcp to check server status, verify command paths, and adjust timeouts in settings.

---

What Is MCP?#

The Model Context Protocol (MCP) is an open standard for connecting AI tools to external data sources and services. Instead of hardcoding integrations, Claude Code discovers and communicates with MCP servers at runtime using a standardized protocol.

With MCP, Claude can:

• Read documents from Google Drive
• Update Jira tickets
• Pull messages and context from Slack
• Automate browsers with Playwright
• Query databases directly
• Interact with any custom tooling your team builds

MCP servers expose tools, resources, and prompts to Claude. Claude decides when to call them based on the task at hand. You configure which servers are available — Claude handles the rest.

---

Configuring MCP Servers#

You have three ways to register MCP servers with Claude Code.

Via CLI#

The fastest way to add a server:

claude mcp add <server-name> -t stdio -- <command> [args]

Example — add a filesystem server scoped to your project:

claude mcp add filesystem -t stdio -- npx @anthropic-ai/mcp-server-filesystem /home/user/project

CLI-added servers are persisted to your settings automatically. Remove them with claude mcp remove <server-name>.

Via settings.json#

For more control, edit ~/.claude/settings.json (global) or .claude/settings.json (project-level). Add an mcpServers object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-filesystem", "/home/user/project"],
      "env": {},
      "cwd": "/home/user/project"
    },
    "github": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

Each server entry supports:

• command — The executable to run (required)
• args — Array of command-line arguments
• env — Environment variables passed to the server process
• cwd — Working directory for the server

Via Agent SDK#

When building programmatic agents, pass MCP servers directly:

{
  "mcp_servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

This is useful for CI pipelines, automated workflows, and custom agent orchestration.

---

Common MCP Server Configurations#

Here are ready-to-use configurations for the most popular MCP servers.

Playwright (Browser Automation)#

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Gives Claude the ability to navigate web pages, click elements, fill forms, take screenshots, and extract content from live sites.

Filesystem#

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-filesystem", "/home/user/project"]
    }
  }
}

Grants read/write access to files within the specified directory. Useful for sandboxed file operations outside the current working tree.

Memory / Knowledge Graph#

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-memory"]
    }
  }
}

Persistent knowledge graph that Claude can use to store and recall entities, relations, and facts across sessions.

GitHub#

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

Create issues, search repos, read pull requests, and manage projects on GitHub. Requires a personal access token with appropriate scopes.

---

OAuth and Authentication#

MCP servers that need user authentication support OAuth flows. Configure custom OAuth discovery by setting oauth.authServerMetadataUrl in the server config:

{
  "mcpServers": {
    "my-api": {
      "command": "node",
      "args": ["my-api-server.js"],
      "oauth": {
        "authServerMetadataUrl": "https://api.example.com/.well-known/oauth-authorization-server"
      }
    }
  }
}

MCP OAuth follows RFC 9728 for protected resource metadata. When a server needs authentication, Claude Code handles the OAuth dance — redirecting you through the consent flow and storing tokens securely.

For subprocess attribution, Claude Code sets the AI_AGENT environment variable on spawned MCP server processes. Downstream services can use this to identify and audit AI-initiated requests.

---

MCP Elicitation#

Starting from v2.1.76, MCP servers can request structured user input mid-task through elicitation. This means a server can pause execution, ask the user a question (with defined input schema), and resume based on the response.

Two hook events are available:

• Elicitation — Fired when the server requests user input
• ElicitationResult — Fired after the user responds

This is useful for servers that need confirmation before destructive operations, credentials that can't be pre-configured, or any workflow requiring human judgment mid-execution.

---

The alwaysLoad Option#

By default, Claude Code defers loading tools from MCP servers until it determines they're needed. This keeps startup fast and reduces context noise. If you want a server's tools to always be available (no search/deferral step), set alwaysLoad:

{
  "mcpServers": {
    "critical-tools": {
      "command": "node",
      "args": ["critical-tools-server.js"],
      "alwaysLoad": true
    }
  }
}

Use this for servers you rely on in every session. Avoid it for large servers with many rarely-used tools — it inflates context unnecessarily.

---

Auto-Retry on Startup Errors#

From v2.1.121, Claude Code automatically retries MCP server startup on transient failures — up to 3 attempts. If a server fails to start (network blip, race condition with dependencies, slow warmup), Claude will retry before marking it as failed.

This reduces flaky server issues in practice. If a server still fails after 3 attempts, check the /mcp status panel for error details.

---

Claude.ai MCP Connectors#

Since v2.1.46, you can use MCP connectors configured on claude.ai directly in Claude Code. If you've set up integrations in the web app — Google Drive, Slack, Notion, etc. — they propagate to your local Claude Code session.

This means no duplicate configuration. Set up a connector once in claude.ai, and it's available everywhere.

---

Troubleshooting Common Issues#

Server Won't Start#

Symptom: Server shows as "failed" in the /mcp panel.

Fix:

1. Verify the command resolves — run it directly in your terminal.
2. Check that dependencies are installed (npm install, pip install).
3. Look for missing environment variables in the env config.
4. Check the server's own logs for startup errors.

Tools Not Showing#

Symptom: Server is connected but tools don't appear in autocomplete or aren't being called.

Fix:

1. Run /mcp to confirm the server status is "connected".
2. Check if tools require specific permissions or allowlists.
3. Try setting alwaysLoad: true to force tool discovery.
4. Restart Claude Code after adding a new server.

Timeout Issues#

Symptom: Server starts but tool calls time out.

Fix:

Increase the timeout in your settings:

{
  "mcpServers": {
    "slow-server": {
      "command": "node",
      "args": ["slow-server.js"],
      "timeout": 60000
    }
  }
}

Default timeout is 30 seconds. Long-running operations (database queries, browser automation) may need 60 seconds or more.

Permission Errors#

Symptom: Claude refuses to call certain tools.

Fix:

Check your tool allowlists and permission settings. Claude Code has safety mechanisms that may block tools based on your configuration. Review allowedTools in settings and ensure the server's tools are permitted.

---

Security#

MCP servers run as local subprocesses with your user's permissions. Treat server configuration with the same care as shell access.

Network Sandboxing#

From v2.1.113, you can restrict server network access using sandbox.network settings:

{
  "mcpServers": {
    "internal-api": {
      "command": "node",
      "args": ["api-server.js"],
      "sandbox": {
        "network": {
          "deniedDomains": ["evil-site.com", "exfiltration.example.net"]
        }
      }
    }
  }
}

deniedDomains blocks outbound requests to specific domains — useful for preventing data exfiltration or isolating untrusted servers.

Best Practices#

• Scope filesystem access — Only grant paths the server genuinely needs.
• Rotate tokens — Don't commit GITHUB_PERSONAL_ACCESS_TOKEN or similar secrets. Use env with vault integration.
• Audit server code — Review what any third-party MCP server does before running it.
• Use deniedDomains — For servers that shouldn't talk to the public internet.

---

MCP turns Claude Code from a standalone coding assistant into a system that can reach into your entire toolchain. Start with a single server — filesystem or GitHub — and expand from there. The protocol is standardized, so every new server works the same way.