How to Set Up MCP Servers for Claude Code: Step-by-Step Guide

Claude Code out of the box can read files, run terminal commands, and edit code. That's powerful, but it's also limited. It can't query your database, call your APIs, search your documentation, or understand your codebase structure — unless you extend it.

MCP servers are how you extend it. They plug new tools directly into Claude Code, letting it do things it couldn't do before. Setting one up takes about 5 minutes, and the productivity impact is immediate.

Here's the complete setup guide, from zero to working MCP server.

What MCP Is (And Why It Matters)

MCP stands for Model Context Protocol. It's an open standard created by Anthropic that defines how AI agents communicate with external tool servers. Think of it as a USB port for AI — a universal interface that lets any compatible tool plug into any compatible agent.

Before MCP, every AI tool had its own proprietary extension system. Cursor had its own plugin format. Copilot had its own. If you built a tool for one agent, you had to rebuild it for every other agent. MCP eliminates this fragmentation. Build one MCP server, and it works with Claude Code, Cursor, Windsurf, Continue.dev, and any other MCP-compatible agent.

An MCP server is a lightweight process that:

1. Exposes tools — functions the agent can call (e.g., "query the database," "search documentation," "get codebase context")
2. Communicates via JSON-RPC — standardized message format over stdio or HTTP
3. Runs locally — on your machine, with access to your local resources (databases, files, APIs)

When Claude Code connects to an MCP server, it discovers the available tools and can use them during coding sessions. The agent decides when to call which tool based on your task — you don't need to invoke them manually.

Why MCP Matters for Claude Code

Without MCP servers, Claude Code's context about your project comes from two sources: files it reads and commands it runs. Both are general-purpose and inefficient for specialized tasks.

With MCP servers, Claude Code gains specialized capabilities:

• Database access — Query your development database directly, inspect schemas, check data states
• API integration — Call internal APIs, check service health, verify endpoint behavior
• Documentation search — Search your team's docs, wikis, or knowledge bases without leaving the coding session
• Context engines — Get dependency-graph-ranked codebase context instead of reading files blindly (this alone can reduce token usage by 58%)
• Deployment tools — Check deployment status, trigger builds, read logs
• Custom tools — Anything your workflow needs: Jira integration, Slack notifications, monitoring dashboards

Each MCP server you add makes Claude Code more capable and more efficient. The agent does more with fewer tokens because it has direct access to information it would otherwise spend tokens exploring for.

Step-by-Step Setup

Step 1: Understand the Configuration File

Claude Code reads MCP server configuration from settings files. There are two locations:

• Project-level: `.claude/settings.json` in your project root (shared with your team via git)
• User-level: `~/.claude/settings.json` (personal, applies to all projects)

The MCP configuration goes in the `mcpServers` object. Each key is a server name, and each value defines how to start the server:

```json

{

"mcpServers": {

"server-name": {

"command": "command-to-start-server",

"args": ["arg1", "arg2"],

"env": {

"ENV_VAR": "value"

}

}

}

}

```

• command: The executable that starts the MCP server (e.g., `node`, `npx`, `python`, or a direct binary path)
• args: Command-line arguments passed to the executable
• env: Optional environment variables for the server process

Step 2: Register Your First MCP Server

Let's start with a simple example — adding the filesystem MCP server that comes with the MCP reference implementations:

```json

{

"mcpServers": {

"filesystem": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]

}

}

}

```

Save this in `.claude/settings.json`. The next time you start Claude Code in this project, it will launch the filesystem server and make its tools available.

Step 3: Verify the Connection

Start Claude Code and ask it to use the server:

```

> What tools are available from the filesystem MCP server?

```

Claude Code should list the tools exposed by the server. If it reports no MCP servers connected, check:

• The settings file is valid JSON (no trailing commas, correct syntax)
• The command is available in your PATH
• The server process can start successfully (try running the command manually in your terminal)

Step 4: Approve Tool Permissions

The first time Claude Code tries to use an MCP tool, it will ask for your permission. You can:

• Allow once — permits this single invocation
• Allow for session — permits all invocations of this tool for the current session
• Allow always — permanently permits this tool (stored in settings)

For MCP servers you trust and use regularly, "allow always" is the practical choice. You can review and revoke permissions in your settings file at any time.

Setting Up vexp as an MCP Server

vexp is one of the highest-impact MCP servers for Claude Code because it gives the agent structural awareness of your codebase — a dependency graph that maps every symbol, import, and relationship. Here's the complete setup:

Install vexp

```bash

npm install -g vexp-cli

```

This installs the vexp CLI globally, making the `vexp` and `vexp-core` commands available.

Initialize Your Project

```bash

cd /path/to/your/project

vexp init

```

This creates `.vexp/manifest.json` (commit this to git) and begins indexing your codebase. Indexing typically takes 10-30 seconds for projects under 100K lines. The index is stored locally in `.vexp/index.db` (automatically gitignored).

Configure MCP

Add vexp to your Claude Code settings. In `.claude/settings.json`:

```json

{

"mcpServers": {

"vexp": {

"command": "vexp-core",

"args": ["mcp", "--workspace", "."]

}

}

}

```

Alternatively, if you installed via npm and `vexp-core` isn't in your PATH, use the npx variant:

```json

{

"mcpServers": {

"vexp": {

"command": "npx",

"args": ["-y", "vexp-cli", "core", "mcp", "--workspace", "."]

}

}

}

```

Verify the Setup

Start Claude Code and run a verification:

```

> Use index_status to check vexp indexing

```

You should see output reporting:

• Number of indexed files
• Number of discovered symbols
• Number of mapped relationships
• Index health status

If the numbers look reasonable for your project size (e.g., a 50K-line TypeScript project typically has 5,000-15,000 symbols), the setup is complete. Claude Code now has structural awareness of your codebase and will use vexp automatically when it needs context.

What Changes After Setup

With vexp configured, Claude Code's behavior changes in measurable ways:

• Exploration drops by 80-90% — the agent queries the graph instead of reading files speculatively
• Token usage drops by 58% on average — less exploration means fewer wasted input tokens
• File references become accurate — the agent works from verified graph data, not guessed paths
• Multi-file changes become reliable — the graph shows all affected files and their relationships

You don't need to change how you prompt Claude Code. The agent discovers vexp's tools automatically and uses them when they're more efficient than file reading.

Testing Your MCP Setup

After configuring any MCP server, verify it's working correctly with these checks:

Check 1: Tool Discovery

Ask Claude Code what MCP tools are available:

```

> List all available MCP tools

```

The response should include the tools from your configured servers. For vexp, you'll see tools like `run_pipeline`, `get_context_capsule`, `get_impact_graph`, `get_skeleton`, and others.

Check 2: Tool Execution

Run a simple tool to confirm end-to-end functionality:

```

> Use the vexp index_status tool to check my project

```

A working setup returns data. A broken setup returns an error or "no MCP server available" message.

Check 3: Integration Quality

Give Claude Code a real task and observe whether it uses the MCP tools:

```

> Explain how the authentication module works in this project

```

With vexp configured, Claude Code should query the dependency graph for auth-related symbols rather than reading files one by one. You can confirm this by watching the tool calls in the conversation — you should see `run_pipeline` or `get_context_capsule` calls rather than multiple file `Read` operations.

Common Setup Issues and Fixes

"Command not found"

The most common error. The command specified in your MCP config isn't in your PATH.

Fix: Use the full path to the executable. Find it with `which vexp-core` or `which node` and use the absolute path in your config:

```json

{

"command": "/usr/local/bin/vexp-core",

"args": ["mcp", "--workspace", "."]

}

```

"Server disconnected" or "Server failed to start"

The server process starts but crashes immediately.

Fix: Run the command manually in your terminal to see the error output:

```bash

vexp-core mcp --workspace .

```

Common causes: missing dependencies, wrong Node.js version, incorrect workspace path, or port conflicts.

Tools Not Appearing

The server connects but Claude Code doesn't show any tools.

Fix: The server may not be implementing the MCP tool registration correctly. Check that the server version is compatible with Claude Code's MCP client version. Update both to latest:

```bash

npm update -g vexp-cli

```

Permission Denied on Tool Calls

Claude Code asks for permission but then fails to execute the tool.

Fix: Check that the server process has access to the resources it needs (file system permissions, database credentials in env vars, API tokens). MCP servers run with the same permissions as your user account, but env vars need to be explicitly passed in the config.

Slow Server Startup

Some MCP servers take several seconds to initialize (building indexes, connecting to databases).

Fix: This is usually expected behavior for the first launch. Subsequent launches are faster if the server caches its state. If startup consistently takes more than 10 seconds, check whether the server is doing unnecessary work on init.

Recommended MCP Servers for Developers

Beyond vexp, several MCP servers are worth adding to your Claude Code setup:

Database servers:

• `@modelcontextprotocol/server-postgres` — Query PostgreSQL databases, inspect schemas
• `@modelcontextprotocol/server-sqlite` — SQLite database access for local development

Knowledge and documentation:

• `@modelcontextprotocol/server-memory` — Persistent key-value memory across sessions
• Sanity MCP server — Query and manage CMS content

Development workflow:

• `@modelcontextprotocol/server-github` — GitHub issues, PRs, and repository management
• `@modelcontextprotocol/server-git` — Advanced git operations

Search and retrieval:

• `@modelcontextprotocol/server-brave-search` — Web search capability
• `@modelcontextprotocol/server-fetch` — Fetch and parse web pages

Each additional MCP server expands what Claude Code can do without leaving your coding session. The compound effect of multiple well-chosen servers transforms Claude Code from a code-focused assistant into a fully integrated development environment that can query databases, search documentation, manage repositories, and navigate your codebase with structural precision — all within a single conversation.

Start with one MCP server (vexp is the highest-impact choice for most developers), verify it works, then add others based on your workflow needs. The setup investment is minimal — 5 minutes per server — and the capability expansion is significant.