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

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. And that part genuinely is straightforward - if you are stuck on it, the two sections linked above are the whole answer, and it is worth saying that plainly rather than waving you past it.

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.

One thing worth knowing before you start, because it changes the advice: tool search is now on by default. Claude Code defers MCP tool schemas and loads only the ones a task needs, so the context cost of adding a fourth server is much lower than it was when I hit that wall. Not zero, though - tool names and each server's instructions still load at session start, so the baseline still grows with server count, just far more slowly. The tiering below still matters for your own sanity, and it is no longer the emergency it once was. How that works is under the context-overhead section, with the full mechanism in MCP Tool Search.

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. Before tool search, Claude read all of it up front to decide which tool fit a given task.

That was the shape of the problem before tool search, and it is worth understanding because it is what the current design exists to solve. With one server and 5 tools it was negligible. With multiple servers and 30+ tools the full schemas added up, and Claude also had to reason about which tool fit the task, so more options meant more reasoning overhead. The second half of that has not gone away.

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, it loads only the tool names and each server's instructions. Claude sees what exists but not the 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, and the prefix stays stable so prompt caching keeps working. What it does not do is make the cost zero: the names and each server's instructions still load every session, so the baseline grows with server count - just far more slowly than it did when every schema loaded upfront.

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. Tool search removed most of the context cost but not all of it - names and per-server instructions still load every session - and every server here is also one more thing Claude has to pick between, in every session, in every project.

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. With tool search on by default the difference in raw context is much smaller than it used to be, though not nothing; what you are mostly buying now is that each session only offers Claude the tools that make sense for it.

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

Tool Search is Claude Code's built-in mechanism for managing large tool sets, and since it is on by default this is a description of what is already happening in your sessions rather than something to switch on. You can turn it off with ENABLE_TOOL_SEARCH=false, or set auto for threshold-based loading, but the default is full deferral.

How It Works

Without Tool Search - which is what you get if you disable it, and what everyone had before it shipped - 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 the tool names and each server's instructions 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. What still scales with server count is the names and per-server instructions, which load every session regardless, so tiering is about keeping that baseline honest rather than about schemas.

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."