UC Jung

Posted on Mar 30

Chapter 3. How to Use — MCP Server

3.1 What is MCP?

MCP (Model Context Protocol) is an open standard protocol that allows Claude Code to connect to external tools, databases, and APIs.

By default, Claude Code can only read/write files, run Bash commands, and perform searches. By connecting MCP servers, its capabilities extend to managing GitHub pull requests, querying databases, automating browsers, performing symbol-level code analysis, and more.

┌──────────────┐     MCP Protocol     ┌──────────────────┐
│  Claude Code  │ ◄──────────────────► │   MCP Server      │
│  (Client)     │                      │  (Tool Provider)  │
└──────────────┘                      └──────────────────┘
                                        ↕
                                      External Services
                                      (GitHub, DB, IDE, etc.)

3.2 Basic MCP Commands

# Add a server
claude mcp add <name> -- <command>

# Add in JSON format (for complex configurations)
claude mcp add-json <name> '{ JSON config }'

# List servers
claude mcp list

# Check server status (inside Claude Code)
> /mcp

# Remove a server
claude mcp remove <name>

# Show server details
claude mcp get <name>

Configuration Scope

Scope	Stored Location	Sharing
`local` (default)	Current project	Only you
`project`	`.mcp.json`	Shared with team (Git commit)
`user`	`~/.claude.json`	All your projects

# Use across all projects (user scope)
claude mcp add --scope user <name> -- <command>

# Share with team (project scope)
claude mcp add --scope project <name> -- <command>

Windows Notes

On Windows, MCP servers that use npx must be wrapped with cmd /c.

# ❌ This will cause an error
claude mcp add my-server -- npx -y @some/package

# ✅ Correct approach
claude mcp add my-server -- cmd /c npx -y @some/package

3.3 Useful MCP Servers

① Serena — Symbol-Level Code Indexing

Purpose: Search and edit code at the symbol level (functions, classes, variables) in large codebases.
While standard Claude Code reads entire files, Serena finds only the exact symbols needed, conserving context.

Key Features

Tool	Description
`find_symbol`	Search for a symbol's definition location
`find_referencing_symbols`	Find code that references a symbol
`insert_after_symbol`	Insert code after a symbol
`replace_symbol_body`	Replace the body of a symbol
`write_memory` / `read_memory`	Save and read memory across sessions

Prerequisites — Install uv

Serena is Python-based, so the uv package manager is required.

# Ubuntu
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

On Windows, use an absolute path instead of $(pwd).

Initial Setup After Installation

# Inside Claude Code
> Start Serena onboarding        ← Analyzes project + creates memory
> Run Serena indexing             ← Creates symbol index (for large projects)

Or index directly from the CLI:

uvx --from git+https://github.com/oraios/serena serena project index

💡 The onboarding process reads many files and consumes a significant amount of tokens.
For large projects, it is recommended to run CLI indexing first.

② Sequential Thinking — Structured Reasoning

Purpose: Breaks down complex problems step by step for systematic thinking.
Useful for architecture design, debugging strategy, and planning complex refactoring.

Installation

# Ubuntu / macOS
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

# Windows (cmd /c wrapper required)
claude mcp add sequential-thinking -- cmd /c npx -y @modelcontextprotocol/server-sequential-thinking

Or configure directly via JSON (edit ~/.claude.json)

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

On Windows, change to "command": "cmd", "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]

Usage Example

> Plan the migration of this project's authentication system to OAuth2.
  Use sequential-thinking to analyze it step by step.

3.4 Cautions — Problems with Too Many MCP Servers

Issues

The more MCP servers you install, the more the following problems arise.

Problem	Description
Context consumption	Each MCP server's tool descriptions occupy space in the context window. The more servers, the less space remains for actual work.
Tool name conflicts	If different MCP servers provide tools with the same name, unexpected behavior occurs. (e.g., conflict between Serena's and the Filesystem server's file-reading tools)
Session startup delay	All MCP servers are initialized at session start, so more servers means slower startup.
Reduced tool selection accuracy	When too many tools are available, Claude's accuracy in choosing the right tool decreases.

⚠️ Recommendation: Keep the number of simultaneously active MCP servers to 3–5 or fewer.

Checking and Compacting Context

Claude Code has a 200K-token context window, and the system prompt, tool descriptions, MCP servers, and conversation history all share this space. The more MCP servers you have, the less working space remains.

Check Context Usage — /context

> /context

Context Usage
claude-opus-4-6 • 51k/200k tokens (26%)

  System prompt:     2.6k tokens (1.3%)
  System tools:     17.6k tokens (8.8%)
  MCP tools:          907 tokens (0.5%)    ← Space occupied by MCP servers
  Custom agents:      935 tokens (0.5%)
  Memory files:       302 tokens (0.2%)
  Messages:         30.5k tokens (15.3%)   ← Grows as conversation lengthens
  Free space:         114k (57.0%)
  Autocompact buffer: 33k tokens (16.5%)   ← Reserved space for auto-compaction

The larger the MCP tools entry, the more context is being consumed by tool descriptions alone.
Use the /mcp command to check the detailed cost per server.

Compact Context — /compact

When the conversation grows long and Free space drops below 30%, run a manual compaction.

> /compact                                    # Compact entire conversation
> /compact preserve API change details        # Instruct what to preserve

Command	Description
`/context`	Displays current token usage by category
`/compact`	Summarizes and compacts conversation history to free up space
`/compact <instruction>`	Compacts while preserving specified content
`/clear`	Fully resets conversation context (when switching tasks)
`/cost`	Shows token cost for the current session

💡 Auto-compact runs automatically when usage reaches approximately 83.5%.
However, running /compact manually first lets you control what content is preserved.

Token Savings with Serena

Because Serena retrieves only the necessary code at the symbol level instead of reading entire files, it saves a significant amount of tokens.

Item	Standard Claude Code	With Serena
Code navigation method	Read entire files (Read)	Symbol-level lookup (find_symbol)
Symbol lookup speed	~45 seconds (grep-based)	~100ms (index-based)
Token reduction rate	—	~70–80% (for large projects)
Most effective for	—	Projects with 100K+ lines
Least effective for	—	Small projects (a few hundred lines)

According to community user reports, applying Serena can reduce tokens by up to 70–80%,
meaning you can work longer before exhausting the context window.
However, for small projects, the indexing overhead may limit the benefit.

Solution — Disable Servers by Use Case

Instead of removing unused MCP servers, disable them so they can be re-enabled when needed.

Method 1: Set disabled: true in .claude.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"],
      "disabled": false
    },
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"],
      "disabled": true
    }
  }
}

Setting "disabled": true keeps the configuration in place but prevents the server from loading in the session.

Method 2: Operate Profiles by Task Type

[Coding tasks]      serena ✅   sequential-thinking ❌
[Design/Analysis]   serena ❌   sequential-thinking ✅
[Full workflow]     serena ✅   sequential-thinking ✅   ← Watch context consumption

When switching tasks, toggle the disabled value in .claude.json, or manage separate configurations using per-project .mcp.json files.

3.5 Summary of MCP Configuration File Locations

File	Location	Purpose
`~/.claude.json`	Home directory	Personal global MCP configuration
`.mcp.json`	Project root	Team-shared MCP configuration (Git commit)
`.claude/settings.json`	Project `.claude/`	Project-local configuration

# Open configuration file
# Windows
notepad $env:USERPROFILE\.claude.json

# Ubuntu
nano ~/.claude.json

3.6 Quick Reference

# ── Basic MCP Commands ───────────────────────────────
claude mcp add <name> -- <command>          # Add
claude mcp add-json <name> '{ JSON }'       # Add via JSON
claude mcp list                             # List
claude mcp remove <name>                    # Remove
> /mcp                                      # Check status (in session)

# ── Install Serena ───────────────────────────────────
# Prerequisite: uv must be installed
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

# ── Install Sequential Thinking ──────────────────────
# Ubuntu/macOS
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
# Windows
claude mcp add sequential-thinking -- cmd /c npx -y @modelcontextprotocol/server-sequential-thinking

# ── Disable ──────────────────────────────────────────
# Set "disabled": true in ~/.claude.json

Reference: https://code.claude.com/docs/en/mcp | https://github.com/oraios/serena

DEV Community