Claude Code MCP: From One Server to a Full Tool System [2026]

Why One Claude Code MCP Server Is Not Enough

Every Claude Code MCP tutorial shows the same thing: add a server, run a command, done. Setting up Claude Code MCP with one server and one tool is the easy part.

The hard part is what happens at server number four, when your tools start overlapping, your context fills up with MCP metadata, and you cannot remember which server handles what. I hit that wall after adding my third server. Context overhead doubled. Claude got slower picking tools because it had to reason about dozens of tool descriptions before doing anything useful.

Now I run multiple MCP servers across my Claude Code setup. They start automatically, never conflict, and give me access to specialized tools without a single manual step per session. Getting there took some architecture decisions.

How Claude Code MCP Configuration Works

Before organizing multiple servers, you need to understand how Claude Code handles MCP configuration. Servers are configured at three scopes:

Adding a Server

The simplest way to add an MCP server is the claude mcp add command:

# Remote HTTP server (most common for SaaS integrations)
claude mcp add --transport http stripe https://mcp.stripe.com

# Local stdio server (for custom or local tools)
claude mcp add my-server -- node /path/to/server.js

# Project-scoped (shared with team via .mcp.json)
claude mcp add --transport http linear --scope project https://mcp.linear.app/mcp

The .mcp.json File

For project-scoped servers, Claude Code creates a .mcp.json file at your project root. This file is designed to be checked into version control so your entire team gets the same tools:

{
  "mcpServers": {
    "kairn": {
      "command": "uvx",
      "args": ["kairn"],
      "env": {
        "KAIRN_DB": "/path/to/knowledge.db"
      }
    }
  }
}

When Claude Code starts, it reads .mcp.json and auto-starts all configured servers. No manual steps. Project-scoped servers require approval on first use for security - Claude Code prompts you before connecting to a server defined in a shared config file.

The Claude Code MCP Context Overhead Problem

Every MCP server advertises its tools to Claude. Each tool comes with a name, description, and parameter schema. Claude reads all of these to decide which tool to use for a given task.

With one server and 5 tools, this is negligible. With multiple servers and 30+ tools, the overhead adds up. Tool descriptions eat tokens from your context window. Claude also needs to reason about which tool fits the task, and more options means more reasoning overhead.

How Tool Search Solves This

Claude Code's Tool Search mechanism addresses this at scale. Instead of loading full tool schemas for every MCP server at startup, Tool Search loads lightweight stubs. Claude sees the tool names but not the full parameter schemas until it actually needs to use a tool.

This means you can have dozens of MCP tools available without paying the full context cost upfront. When Claude decides to use a specific tool, it calls ToolSearch to load the full schema on demand. The prefix stays stable, prompt caching works efficiently, and context overhead stays flat regardless of how many tools you have.

Organizing MCP Servers by Tier

Claude Code's three official scopes (Local, Project, User) control where servers load. On top of this, I add a mental model for what loads when:

Tier 1: Always-On

User-scoped servers that load in every session. These are infrastructure tools you always need regardless of which project you're working on. Keep this tier small - every server here adds to the baseline context of every session.

Examples: browser automation, documentation lookup, hosting management.

Tier 2: Domain

Project-scoped servers shared via .mcp.json for a specific workspace. These add domain-specific capabilities without affecting other projects.

Examples: a knowledge graph server for your AI system, a content management server for your blog, a monitoring server for your production stack.

Tier 3: Project-Specific

Local-scoped servers for tools unique to one project. These stay private and don't pollute other workspaces.

A lightweight project session starts with Tier 1 only. A full workspace session loads Tiers 1 + 2. The difference in context overhead is meaningful across a long session.

Setting Up Your First MCP Server

Start with one server that solves a real pain point. The most common entry points:

Connect a SaaS Tool

Most popular SaaS tools now offer MCP servers. The Claude Code MCP docs list servers for Linear, Figma, Sentry, Amplitude, Atlassian, GitHub, and many more. Setup is typically one command:

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

After adding, Claude Code can directly interact with your Linear issues, create tasks, and update status - no copy-pasting between browser and terminal.

Connect a Database

For database access, use a local stdio server:

claude mcp add postgres -- npx @modelcontextprotocol/server-postgres \
  "postgresql://user:pass@localhost:5432/mydb"

Now Claude can query your database directly, understand your schema, and write queries that reference your actual table structure.

Connect a Knowledge System

This is where MCP becomes genuinely powerful. Instead of Claude reading flat files for context, a knowledge MCP server gives it structured, searchable access to your accumulated knowledge.

Kairn is the MCP server I built for this - 19 tools for semantic memory, knowledge graphs, and experience tracking:

{
  "mcpServers": {
    "kairn": {
      "command": "uvx",
      "args": ["kairn"]
    }
  }
}

With Kairn connected, Claude can kn_recall past decisions, kn_query the knowledge graph, and kn_learn new findings - all through MCP tools instead of manual file reads.

Building a Custom MCP Server

Off-the-shelf servers cover common integrations. But MCP becomes a true differentiator when you build servers that know YOUR system.

When Custom Makes Sense

Build a custom MCP server when:

• You have domain knowledge Claude needs that no existing server provides
• You're copying the same data into Claude sessions repeatedly
• You want Claude to interact with internal tools or APIs
• You need tools designed for your specific workflow patterns

What I Built

My custom knowledge management server wraps memory, experiences, graph navigation, and project state into one MCP server. The session startup pattern is where this pays off:

Claude boots, queries the knowledge graph for relevant context, checks past experiences for lessons learned - all through MCP tools. No manual file reading. No "let me check the memory files."

The hooks system ties in naturally - hooks can trigger MCP tool calls, and MCP tools can enforce hook-like policies.

Getting Started with Custom Servers

The MCP specification is an open standard. You can build a server in Python (using the mcp SDK), TypeScript, or any language that speaks JSON-RPC over stdio or HTTP.

For Python, the minimal pattern:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(query: str) -> str:
    """Search my knowledge base for relevant information."""
    # Your logic here
    return results

mcp.run()

Add it to your .mcp.json and it auto-starts with every session.

MCP Tool Search: Scaling Without Context Bloat

As your MCP server count grows, Tool Search becomes essential. It's Claude Code's built-in mechanism for managing large tool sets efficiently.

How It Works

Without Tool Search, every MCP tool's full schema (name, description, parameters) loads into the context window at startup. With 50+ tools, that's thousands of tokens of overhead on every request.

Tool Search changes this:

1. At startup, only lightweight tool stubs (name + one-line description) load into the prefix
2. When Claude needs a tool, it calls ToolSearch with a query
3. The full schema loads on demand, only when needed
4. The static prefix stays stable, so prompt caching works efficiently

This means you can scale to dozens of MCP tools without degrading session performance. The cost is one extra round-trip when Claude first uses a tool - negligible compared to the context savings.

For Server Authors

If you're building MCP servers, design tool descriptions for Tool Search discoverability. Short, specific names and clear one-line descriptions help Claude find the right tool. Group related tools with consistent prefixes (like Kairn's kn_ prefix) so they're searchable as a set.

Before and After: What a Multi-Server Setup Changes

The biggest win is not speed. It's accuracy. When Claude uses structured MCP tools instead of keyword-searching through files, it finds relevant context it would otherwise miss. My knowledge architecture explains why graph navigation beats flat file search - MCP is the protocol that makes it practical.

Start With One, Think in Tiers

You do not need multiple servers on day one. Start with one that solves a real pain point:

1. If you constantly look up docs - add a documentation server
2. If you need web content - add a scraping server
3. If you have a growing knowledge base - add Kairn or build a custom server

But think in tiers from the start. User scope for infrastructure. Project scope for domain tools. Local scope stays minimal. This architecture compounds as you add servers because each new tool lands in the right tier instead of bloating every session.

The protocol itself is straightforward. The architecture around it - scoping, tiering, Tool Search, caching - is what separates "I added an MCP server" from "MCP runs my entire workflow."