Claude Code × MCP Integration Guide: From Server Setup to Agent Usage

The next question engineers typically hit after picking up Claude Code is, "How do I connect it to external tools?" You want to pull GitHub issues automatically, query a database directly, or push notifications to Slack. Writing one-off API-calling scripts for each of those is not a sustainable answer. MCP (Model Context Protocol) was designed precisely to solve this problem. This article walks through configuring MCP servers in Claude Code, building your own, integrating with the SDK, and the usage patterns that come up in real work — with actual commands and configuration examples along the way.

What Is MCP and Its Role in Claude Code

MCP (Model Context Protocol) is a protocol Anthropic open-sourced at the end of 2024. It defines a standard specification for connecting AI agents to external tools and data sources — we cover it in depth in What Is MCP? The New Standard for AI Agent Integration. Here we'll focus on the essentials through the lens of Claude Code.

The Problem MCP Solves

Historically, giving Claude Code external capabilities meant ad-hoc workarounds: having it run curl against a prompt-specified URL, or writing dedicated shell scripts and invoking them. Three or four tools is manageable. Past ten, the management overhead grows sharply.

MCP is often likened to "USB-C for AI agents and tools." Once an MCP client (Claude Code, in this case) supports the protocol, adding a new tool is as simple as adding another MCP server. Claude Code has had MCP client functionality built in since early 2025 — no separate install needed.

Where MCP Sits in Claude Code

MCP's role in Claude Code boils down to three things:

Role	Description
Tool extension	Enables operations beyond Claude Code's built-ins: filesystem manipulation, web search, API calls
Context injection	Lets Claude consume database contents or documents as resources
Workflow automation	Combine multiple MCP servers to complete complex business flows within a single conversation

As of April 2026, the MCP ecosystem includes more than 251 vendor-verified servers. GitHub, Slack, PostgreSQL, Figma — most major services and tools are already available as MCP servers.

Transport Types

There are two main ways to communicate with an MCP server:

Transport	Communication	Use case
stdio	Local process stdin/stdout	Local development, individual use
HTTP/SSE	HTTP-based remote communication	Team sharing, cloud service integration

The stdio approach launches the MCP server as a child process of Claude Code and communicates over stdin/stdout. Setup is simple and, because everything stays local, authentication rarely becomes a problem.

The HTTP/SSE approach connects to a remote MCP server over HTTP. Use this when connecting to servers hosted by the service provider themselves — like the GitHub MCP server. It also supports OAuth for secure access control.

In my experience, the natural division is: run my own MCP servers locally over stdio, and use HTTP/SSE for SaaS integrations.

Configuring MCP Servers

There are two ways to configure MCP servers: via CLI command, or by editing the configuration file directly.

Adding via CLI

The easiest route is claude mcp add.

# Add a local server over stdio
claude mcp add --transport stdio my-server npx -y @example/mcp-server

# Add a remote server over HTTP/SSE
claude mcp add --transport http github-server https://api.githubcopilot.com/mcp/

The basic syntax:

claude mcp add --transport <stdio|http> <server-name> <command-or-URL> [args...]

You can control the configuration scope with the scope flag:

# Project scope (default): saved to .mcp.json
claude mcp add --transport stdio my-server command

# User scope: saved to ~/.claude/settings.json
claude mcp add --scope user --transport stdio my-server command

To list configured servers:

# List registered MCP servers
claude mcp list

# Details for a specific server
claude mcp get my-server

Remove servers that are no longer needed with claude mcp remove:

claude mcp remove my-server

Managing via the Configuration File

For team development, the practical approach is to include the configuration file in the repository. Place .mcp.json at the project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "type": "stdio"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "http"
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "type": "stdio",
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Configuration fields:

Field	Description	stdio	HTTP
`command`	Launch command	Required	Not used
`args`	Command arguments	Optional	Not used
`url`	Server URL	Not used	Required
`type`	Transport type	`"stdio"`	`"http"`
`env`	Environment variables	Optional	Optional

Put per-user configuration in ~/.claude/settings.json:

{
  "mcpServers": {
    "slack-notifier": {
      "command": "node",
      "args": ["/Users/me/mcp-servers/slack-server.js"],
      "type": "stdio",
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

Project scope (.mcp.json) takes precedence over user scope (~/.claude/settings.json). If both define a server with the same name, the project-side config wins.

Handling Environment Variables

When passing API keys or tokens to an MCP server, use the env field. But if you're committing .mcp.json to the repo, be careful not to embed secrets directly.

My approach is to put only the variable names in .mcp.json, and keep the actual values in a local .env file or shell environment:

{
  "mcpServers": {
    "my-service": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "type": "stdio",
      "env": {
        "API_KEY": "${MY_SERVICE_API_KEY}"
      }
    }
  }
}

Using shell variable expansion syntax like this keeps secrets out of .mcp.json itself, so you can safely version-control the file.

Using Built-In MCP Servers

Claude Code ships with a handful of built-in MCP servers you can use without any extra install. These are tools Claude Code provides itself, accessed through the MCP protocol.

Filesystem Server

Claude Code's basic file operations are implemented internally as MCP Tool primitives — Read, Write, Edit, Glob, and the like. No explicit configuration needed; they're usable from day one.

If you need access to directories outside the project, you'll want to add an external filesystem MCP server:

claude mcp add --transport stdio fs-extra npx -y @modelcontextprotocol/server-filesystem /path/to/other/directory

Web Search

Claude Code can also access external web-search capabilities via MCP. It's useful when you want to look up the latest technical information or documentation mid-task.

Tool Search (on-demand tool discovery)

If you register many MCP servers, the number of available tools can blow up and pressure the context window. Claude Code addresses this with a mechanism called Tool Search.

Rather than loading every tool definition into context up front, Tool Search dynamically discovers and loads only the tools relevant to the current task. The result is said to reduce context usage by up to 95%.

The mechanism: Claude Code analyzes the user's instruction, queries MCP servers for potentially relevant tools, and only adds the matched tools' schemas to context. Even when you have 50 or 100 tools available, a single task typically needs only a handful — which makes this optimization dramatically effective.

In my own project I have four MCP servers registered (GitHub, PostgreSQL, Slack, Figma), but thanks to Tool Search I barely feel any context pressure. For tasks that only involve reading and writing files, the external MCP servers' tools never touch the context at all.

Running Claude Code Itself as an MCP Server

A lesser-known feature: Claude Code can also act as an MCP server.

claude mcp serve

Running this launches Claude Code as a stdio-based MCP server. Other MCP clients — for example Claude Desktop or another AI agent — can then invoke Claude Code's capabilities.

This is valuable in scenarios like using Claude Code's analysis in a CI/CD pipeline, or borrowing Claude Code's sophisticated code understanding from a different AI agent framework. Having a standard protocol is what makes this kind of interop feel natural.

Building a Custom MCP Server

When existing MCP servers can't cover your requirements, the answer is to build your own. MCP SDKs are available in multiple languages; here are examples in TypeScript and Python.

Building with TypeScript

A minimal server implementation using the TypeScript MCP SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-custom-server",
  version: "1.0.0",
});

// Tool definition
server.tool(
  "get_project_stats",
  "Gather code statistics for the project",
  {
    directory: z.string().describe("Target directory path"),
    extensions: z.array(z.string()).optional().describe("Target file extensions (e.g., ['.ts', '.tsx'])"),
  },
  async ({ directory, extensions }) => {
    // Business logic goes here
    const stats = await collectStats(directory, extensions);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(stats, null, 2),
        },
      ],
    };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

claude mcp add --transport stdio project-stats node /path/to/my-server.js

Or declare it in .mcp.json:

{
  "mcpServers": {
    "project-stats": {
      "command": "npx",
      "args": ["tsx", "./mcp-servers/project-stats.ts"],
      "type": "stdio"
    }
  }
}

Building with Python

Here's the equivalent using the Python MCP SDK:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-python-server")

@mcp.tool()
def query_database(query: str, database: str = "main") -> str:
    """Run a SQL query against the specified database.

    Args:
        query: The SQL query to execute
        database: Target database name
    """
    # Database query execution logic
    result = execute_query(database, query)
    return format_result(result)

@mcp.tool()
def analyze_logs(log_path: str, level: str = "ERROR") -> str:
    """Parse a log file and extract entries at or above the given level.

    Args:
        log_path: Path to the log file
        level: Log level to filter at
    """
    entries = parse_log_file(log_path, level)
    return format_entries(entries)

if __name__ == "__main__":
    mcp.run(transport="stdio")

claude mcp add --transport stdio log-analyzer python /path/to/my_server.py

Exposing Resources

Beyond tools, you can also expose resources (read-only data):

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "docs-server",
  version: "1.0.0",
});

// Static resource
server.resource(
  "project-readme",
  "file:///project/README.md",
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        text: await readFile("./README.md", "utf-8"),
        mimeType: "text/markdown",
      },
    ],
  })
);

// Dynamic resource (template)
server.resource(
  "db-schema",
  new ResourceTemplate("db://schema/{tableName}", { list: undefined }),
  async (uri, { tableName }) => {
    const schema = await getTableSchema(tableName);
    return {
      contents: [
        {
          uri: uri.href,
          text: JSON.stringify(schema, null, 2),
          mimeType: "application/json",
        },
      ],
    };
  }
);

Exposed resources can be referenced automatically as context Claude Code needs for its tasks. Publishing database schemas or project docs as resources lets Claude generate code grounded in accurate information.

Design Considerations for Custom Servers

Some notes from building custom MCP servers myself:

Keep tools at the right granularity. Packing too many capabilities into a single tool makes it hard for the AI model to decide when and how to use it. Aim for "one tool, one responsibility" and write concrete descriptions.

Handle errors carefully. If an MCP server crashes, it affects the entire Claude Code session. Wrap calls in try/catch and return clear error messages.

Validate inputs with a schema. Use Zod in TypeScript or Pydantic in Python to type-check input parameters strictly — this prevents errors from bad inputs. The MCP SDKs integrate naturally with these validation libraries, so type-safe implementations are easy.

Be mindful of idempotency. The AI model may invoke the same tool multiple times. For tools that write data or call external APIs, design them so that repeated invocations are safe.

Integrating with the Claude Code SDK

The Claude Code SDK lets you use Claude Code's capabilities programmatically. Combined with MCP servers, you can build sophisticated AI agent systems.

SDK Overview

The Claude Agent SDK is a framework that provides the building blocks for AI agents. It ships with an MCP client built in, so you can let the SDK hand MCP server tools to your agents.

import { Agent, MCPServerStdio, MCPServerHTTP } from "claude-agent-sdk";

// stdio-transport MCP server
const filesystemServer = new MCPServerStdio({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/project"],
});

// HTTP-transport MCP server
const githubServer = new MCPServerHTTP({
  url: "https://api.githubcopilot.com/mcp/",
});

// Define an agent
const agent = new Agent({
  name: "code-reviewer",
  model: "claude-sonnet-4-20250514",
  instructions: "An agent that performs code reviews and suggests improvements.",
  mcpServers: [filesystemServer, githubServer],
});

// Run the agent
const result = await agent.run("Review the PR changes and flag improvements.");
console.log(result.output);

Using MCP in Subagents

The Claude Agent SDK lets you build hierarchies where a main agent invokes subagents. Assigning different MCP servers to each subagent cleanly separates concerns.

import { Agent, MCPServerStdio } from "claude-agent-sdk";

// Database-only subagent
const dbAgent = new Agent({
  name: "db-agent",
  model: "claude-haiku-4-20250514",
  instructions: "Handles database queries. Only safe SELECT statements are allowed.",
  mcpServers: [
    new MCPServerStdio({
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-postgres"],
      env: { DATABASE_URL: process.env.DATABASE_URL },
    }),
  ],
});

// Code-analysis subagent
const codeAgent = new Agent({
  name: "code-agent",
  model: "claude-sonnet-4-20250514",
  instructions: "Handles source code structural analysis and quality assessment.",
  mcpServers: [
    new MCPServerStdio({
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/project/src"],
    }),
  ],
});

// Main agent (uses subagents as tools)
const mainAgent = new Agent({
  name: "project-analyst",
  model: "claude-sonnet-4-20250514",
  instructions: `
    An agent that performs end-to-end project analysis.
    Use db-agent for checking database state
    and code-agent for code analysis.
  `,
  tools: [dbAgent.asTool(), codeAgent.asTool()],
});

const result = await mainAgent.run(
  "Check consistency between this project's database schema and source code."
);

The benefit of this design is that each subagent's permissions can be tightly scoped. The DB agent can only touch the database; the code agent can only touch the filesystem. From a security standpoint, that's an important design decision.

Tool Permission Control

MCP server tools are subject to Claude Code's permissions system. Destructive operations (deleting files, writing data, etc.) do not run without explicit user permission.

When building a custom server, clearly distinguish whether a tool is read-only or involves writes, and document that in the description. Claude Code uses the description content as one input into deciding whether to prompt the user.

Real-World MCP Use Cases

Here are the MCP use cases my team at aduce actually uses.

GitHub Integration

The most frequently used is the GitHub MCP server.

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

This single setup enables things like:

Fetching the list of issues and reviewing their contents
Creating pull requests and posting review comments
Managing repository branches and tags
Checking GitHub Actions workflow status

Tell Claude Code "look at Issue #42 and draft an implementation plan," and it will fetch the issue via the GitHub MCP server, cross-reference the codebase, and propose an approach. I use this workflow daily, and it's completely eliminated the open-issue-and-copy-paste shuffle.

Database Queries

With the PostgreSQL MCP server, Claude Code can run queries directly:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "type": "stdio",
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

For a prompt like "look at the users table schema and create a new migration file," Claude Code references the actual schema while generating an accurate migration SQL.

Critical principle: only connect to development databases. Avoid connecting to production — the risk of an accidental write query is real. I create a read-only user specific to the development database and give only those credentials to the MCP server.

Slack Notifications

A use case for pushing notifications on CI/CD completion or task completion:

claude mcp add --transport stdio slack npx -y @modelcontextprotocol/server-slack

When a long-running code generation or refactor finishes, telling Claude Code "notify the #dev channel when done" automatically shares completion with the team.

Figma Design Integration

The Figma MCP server lets Claude Code consume design file information directly:

claude mcp add --transport stdio figma npx -y @anthropic/mcp-server-figma

Ask "generate React components from this Figma design," and Claude Code reads the Figma layout, color values, and fonts directly, producing components faithful to the design. It's a use case that dramatically cuts the "telephone game" between design and code — one we're actively rolling out across our team.

Combining Multiple Servers into Workflows

MCP really pays off when you combine multiple servers. Here's an actual .mcp.json I use:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "http"
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "type": "stdio",
      "env": {
        "DATABASE_URL": "${DEV_DATABASE_URL}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "type": "stdio",
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

With this setup, I can run an end-to-end flow inside a single conversation:

Fetch the details of a bug report from a GitHub issue
Inspect the database schema to identify the cause
Generate and apply a fix
Run tests to confirm the fix
Create a pull request
Post a review request in Slack

Previously this meant opening a browser for GitHub, firing up a DB client, writing code in the editor, running tests in the terminal, heading back to GitHub to open the PR, and messaging Slack — all manually. Now, it's a single natural-language instruction to Claude Code.

Checklist for Adopting MCP Servers

A list I run through when introducing a new MCP server:

Check	Detail
Credential management	Manage API keys and tokens via env vars; don't embed them in config files
Least privilege	Give MCP servers the minimum credentials needed
Production isolation	Don't connect directly to production databases or services
Logging	Log requests and responses in custom servers
Fallback on failure	Have a fallback path when an MCP server is unavailable
Team alignment	Get team agreement on which MCP servers to use and their permission scope

Summary

This article walked through how Claude Code and MCP together enable external tool integration. Recapping the key points:

MCP is an open protocol Anthropic released at the end of 2024, providing a standardized interface between AI agents and external tools. Claude Code ships with built-in MCP client functionality — you can add servers with claude mcp add or via .mcp.json.

The stdio and HTTP/SSE transports fit different purposes, and on-demand tool discovery via Tool Search allows efficient context usage. You can build custom servers in TypeScript or Python, and the Claude Agent SDK lets you construct sophisticated systems where subagents hold MCP tools.

MCP's essential value lies in extending the range of tools AI agents can use through a unified approach. We're shifting from writing one-off API integration code toward a protocol-based plugin architecture — and MCP is the core of that shift.

For the basics of Claude Code, see the Claude Code Usage Guide. For deeper conceptual grounding in MCP, see What Is MCP? The New Standard for AI Agent Integration.

If you have questions about building AI agent systems with MCP, or adopting Claude Code, feel free to reach out via our Contact page.