← All Guides
intermediate 30 minutes

Connecting Claude to External Tools with MCP

claude-codemcp
Guide: Connecting Claude to External Tools with MCP

Your AI assistant is smart but isolated. It can reason about code, refactor a module, and explain a stack trace — but it can’t check your production database, query your project management API, or look up a customer record. Everything outside the local filesystem is a wall.

The Model Context Protocol (MCP) removes that wall. It’s an open standard that lets you connect Claude Code to external tools and services through a simple server pattern, and once you’ve set up your first connection, Claude stops being limited to what’s on your local disk.

By the end of this guide, you’ll have at least one MCP server running, connected to Claude Code, and usable in your normal workflow.

What you’ll need

  • Claude Code — installed and working. If you haven’t set it up yet, follow Anthropic’s installation guide.
  • Node.js 18+ — most MCP servers are Node packages. Check with node --version.
  • A service to connect — a database, an API, a SaaS tool, even just extended filesystem access. You need a reason, not just the protocol.

How MCP works (the 60-second version)

MCP servers are small programs that sit between Claude and an external service. They expose tools (actions Claude can take), resources (data Claude can read), and prompts (pre-built instructions) through a standardised interface.

When Claude Code starts, it loads your configured MCP servers and treats their tools the same way it treats its built-in tools like Bash, Read, and Edit. If you’ve connected a GitHub server, Claude can create issues. If you’ve connected a database server, Claude can run queries. The AI doesn’t need special instructions — it sees the available tools and uses them when relevant.

There are two transport types:

  • stdio — the server runs as a local process. Claude communicates with it through standard input/output. This is what you’ll use for most setups.
  • SSE — the server runs remotely and communicates over HTTP. Useful for shared team servers or cloud-hosted services.

For this guide, we’re focusing on stdio servers because they’re simpler to set up and cover most use cases.

Add your first MCP server

The fastest way to connect a server is Claude Code’s built-in command:

claude mcp add <name> -- <command> [args...]

Let’s start with something concrete. The filesystem server gives Claude access to directories outside your current project — useful if you work across multiple folders or need to reference documents stored elsewhere.

Step 1: Add the server

claude mcp add filesystem -- npx -y @anthropic/mcp-server-filesystem /Users/you/Documents /Users/you/Downloads

Replace the paths with directories you actually want Claude to access. Each path you list is a directory the server will expose — and only those directories. Claude can’t wander outside them.

Step 2: Verify it loaded

Start a new Claude Code session (MCP servers load at startup, so you need a fresh session after adding one). Then ask Claude something that requires the new capability:

What files are in my Documents folder?

If you see a response listing your files, the server is working. If Claude says it can’t access that directory, check the paths you provided in step 1.

Step 3: Check the configuration

The claude mcp add command writes to your settings file. You can see what’s configured:

cat ~/.claude/settings.json

The relevant section looks like this:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem",
               "/Users/you/Documents",
               "/Users/you/Downloads"]
    }
  }
}

You can also edit this file directly — sometimes that’s easier than running claude mcp add repeatedly.

A more useful example: GitHub

The filesystem server is a good test, but the real value shows up when you connect to services with APIs. The GitHub MCP server lets Claude create issues, manage pull requests, search repositories, and read code — all within your normal conversation.

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

This server reads your GITHUB_TOKEN environment variable for authentication. If you don’t have one set, create a personal access token with the scopes you need (usually repo and read:org), then export it:

export GITHUB_TOKEN=ghp_your_token_here

Or pass it through the server configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Now Claude can do things like “create a GitHub issue for the bug we just found” or “show me the open PRs on this repo” without you switching to the browser. The workflow stays in one place.

Global vs. project-level configuration

MCP configuration lives in two places:

  • ~/.claude/settings.json — global. These servers load for every project. Good for general-purpose tools like web search, GitHub, or filesystem access.
  • .claude/settings.local.json — project-level. These servers only load when you’re working in that project directory. Good for project-specific databases, APIs, or services.

The .local.json variant is gitignored by default, which is what you want — it often contains environment-specific paths or credentials that shouldn’t be committed.

A reasonable setup looks like this: GitHub and web search in your global config (you want them everywhere), and your project’s database server in the project-level config (you only need it for that codebase).

More tools, less context — the trade-off that bites

Here’s where MCP gets tricky, and where the initial excitement tends to wear off.

Every MCP tool Claude knows about takes up space in its context window. The tool name, its description, its parameter schema — all of that is loaded at the start of every conversation. Add five servers with ten tools each, and you’ve consumed a meaningful chunk of your available context before you’ve typed a single prompt.

Cloudflare ran into this when they built their MCP integration. Their API has around 2,500 endpoints. Exposing each one as a separate tool would have been unusable — the tool descriptions alone would have overwhelmed the context window. Their solution was to collapse everything into just two tools: one that lists available endpoints, and one that calls a specific endpoint. The AI reasons about which endpoint to call, then makes the request through a single generic tool.

You probably don’t have 2,500 endpoints to worry about. But the principle matters: more tools doesn’t mean more capability if the tools starve your actual conversation of context.

In practice, this means:

  • Audit what you’ve connected. Run claude mcp list to see your active servers. If you’re loading servers you haven’t used in weeks, remove them.
  • Prefer servers with fewer, well-designed tools over servers that expose every possible action.
  • Use project-level configuration to limit which servers load for which work. Your email server doesn’t need to be running when you’re debugging a CSS layout.

When to build your own vs. use existing

The MCP server ecosystem is growing fast, and for common services — GitHub, Slack, databases, web search — there’s probably a server that already exists.

Check existing options first. Building your own MCP server is straightforward (it’s a Node script that implements a defined protocol), but maintaining it is ongoing work. If an actively maintained community server covers 80% of what you need, use it.

Build your own when:

  • Your service has no existing server. Internal APIs, custom databases, proprietary tools.
  • You need tight permission scoping. An existing server might expose more actions than you want Claude to have. A custom server can expose exactly the three operations you trust.
  • You’re wrapping a CLI tool. If you already have a working command-line tool for a service, wrapping it as an MCP server is often simpler than finding a standalone server.

The build-vs-use decision is practical, not philosophical. If your API has good documentation and an existing SDK, a basic MCP server is a few hours of work. If your service is complex and the existing server is actively maintained, don’t reinvent it.

Permission scoping — give Claude the least it needs

When you connect external services, think about what Claude can actually do through each connection. A GitHub token with full admin:org scope is more than Claude needs to create issues. A database connection with write access is more than Claude needs to answer questions about your data.

Principle of least privilege applies here the same way it applies everywhere in security:

  • Use read-only database connections unless you specifically want Claude to write data.
  • Scope API tokens narrowly. Create dedicated tokens for MCP use with only the permissions the server needs.
  • Separate read and write servers if your service supports it. You might want Claude to always be able to query your database, but only write to it in specific projects.

Claude will ask for your permission before using MCP tools anyway (unless you’ve explicitly approved them), but defense in depth matters. If the token can’t do damage, neither can a bad prompt.

What to expect once it’s running

The first thing you’ll notice is that your conversations get more grounded. Instead of Claude reasoning abstractly about what your database probably contains, it can check. Instead of generating a GitHub issue template and telling you to paste it, it can create the issue directly.

The second thing — and this tends to sneak up on you — is that the workflow compounds. Once Claude can access your services, you start asking different questions. “Check if this user exists in the database and if they do, create a GitHub issue with their details” becomes a single prompt instead of a three-tab workflow.

Watch for a few rough edges:

  • Servers that crash silently. If a tool stops working mid-conversation, check whether the server process is still running. claude mcp list shows the status.
  • Authentication expiry. Tokens expire. If Claude suddenly can’t access a service it used to reach, check your credentials first.
  • Tool sprawl. It’s tempting to connect everything. Resist that until you have a specific workflow in mind for each server.

Where to go from here

  • Browse existing servers at the MCP servers repository. Filter by your tech stack and add what’s relevant.
  • Build a persistent knowledge system — once you understand MCP, connecting Claude to a vector database or note-taking system is the natural next step.
  • Set up project-level configurations for your most active projects. Match the tools to the workflow, not the other way around.
  • Read Anthropic’s MCP documentation if you want to build your own server. The protocol is well-documented and the SDK handles most of the boilerplate.