Configure MCP Servers in Claude Code With Subagents

Configure an MCP Server in Three Steps

To install an MCP server and configure it in Claude Code, run three commands. This is the minimum path. The rest of the guide covers transports, subagents, scopes, managed enterprise configuration, and building custom MCP servers.

Step 1: Install the MCP server. Pick a transport (stdio for local, http for remote) and point Claude Code at the server. The claude mcp add command registers it.

claude mcp add --transport stdio my-database \
  -- npx @modelcontextprotocol/server-postgres postgresql://localhost:5432/mydb

Step 2: Configure the scope. Decide whether the MCP server config is personal (default), shared with your team via .mcp.json, or centrally managed by an administrator. Scope controls where the configuration lives and who sees it.

# Personal (default): only you see it
claude mcp add --transport stdio my-database -- npx ...

# Project: shared via .mcp.json (commit to git)
claude mcp add --scope project --transport stdio my-database -- npx ...

Step 3: Verify the install. List the connected servers and inspect the tool inventory for the one you just added. Tools should appear in the Claude Code session immediately.

claude mcp list
claude mcp get my-database

If the server is connected but no tools appear, or if it never connects at all, jump to Troubleshooting below before reading the rest of the guide.

Troubleshooting Common MCP Setup Errors

Four failure modes cover most first-install issues.

Server shows "disconnected" in claude mcp list. The server process crashed on startup. Run the exact install command manually in a terminal and read stderr. Common causes: npx not installed, wrong npm package name, missing environment variable passed via -e.

Tools do not appear after claude mcp add. Use the /mcp slash command inside the Claude Code session to force a reconnect. If tools still do not appear, run claude mcp get <name>. An empty tool list means the server started but declared no tools (usually a server-side config error).

Permission denied or OAuth redirect loop (HTTP transport). The remote server requires authentication. Run claude mcp get <name> to see the auth URL and complete the OAuth flow in a browser. If the loop repeats, the service account token has expired. Revoke and re-add.

Wrong protocol version. Claude Code's MCP client speaks MCP v1.0. Servers built against older drafts refuse to connect. Update the server package or check its README for a version compatible with current Claude Code.

Why MCP Servers Matter

The first time we connected an MCP server to Claude Code, the goal was mundane: query a Postgres database while working through a migration, without switching between terminals. Claude Code was open in one pane, a psql session in another, and a browser with the schema docs in a third. It was functional but fractured.

The Model Context Protocol came up in a thread about AI tooling. After confirming that Claude Code supported it natively, a database MCP server was running within fifteen minutes. Claude could query the schema directly. No terminal switching. No copy-pasting query results.

That was the moment MCP servers clicked. They are not plugins in the traditional sense. They are not extensions bolted onto the side of an application. They are a communication protocol that lets Claude Code talk to any external system through a standardised interface. Databases, APIs, file systems, monitoring tools, deployment pipelines. If something exposes an MCP server, Claude Code can use it as naturally as it reads files or runs shell commands.

MCP servers have become the backbone of how AI agents interact with external services in production. The rest of this guide goes from that first claude mcp add command through to enterprise-grade managed configurations and custom subagents.

The Problem

Claude Code is remarkably capable out of the box. It reads files, writes code, runs commands, searches codebases. For a self-contained development workflow, that is often enough. But real projects do not live in isolation.

Your application talks to a database. Your team communicates through Slack. Your infrastructure runs on AWS or GCP. Your issues live in Linear or Jira. Your documentation lives in Notion or Confluence.

Without MCP servers, interacting with these systems from Claude Code means one of two things. Either you shell out to CLI tools (which works but is brittle and verbose) or you leave Claude Code entirely and context-switch to another application. Both approaches break the flow of conversation. You lose the thread of what you were doing.

MCP servers solve this by giving Claude Code a structured way to interact with external tools. The Model Context Protocol is an open standard developed by Anthropic for connecting AI models to external data sources and tools. It defines a client-server architecture where Claude Code acts as the client and external services expose capabilities through a well-defined API.

Each MCP server declares what tools it offers, what inputs they expect, and what outputs they produce. Claude Code discovers these tools at startup and can call them during a conversation just like it calls its built-in tools. This protocol-based extensibility is a fundamental architectural difference from editor-embedded assistants, which we explore in detail in our Claude Code vs Cursor comparison.

The protocol handles serialisation, error handling, and lifecycle management. You do not need to write glue code or build custom integrations. If an MCP server exists for the service you need, connecting it is a configuration change, not a development project.

The practical difference is significant. Instead of asking Claude to "run this SQL query and tell me what it says", you ask Claude to "check how many users signed up this week" and it calls the database tool directly, interprets the results, and continues the conversation. Instead of saying "look at the latest Sentry errors", you ask Claude to "find any new exceptions related to the payment module" and it queries your error tracking system in context.

This guide walks through how to set all of that up.

The Journey

Understanding MCP Transports

MCP servers communicate with Claude Code through one of three transport mechanisms. The transport determines how messages are exchanged between Claude Code and the server process.

stdio is the transport for local MCP servers. Claude Code spawns the server as a child process and communicates over standard input and output. This is the simplest setup. The server runs on your machine, starts and stops with your Claude Code session, and has access to your local file system and network. Most community MCP servers use stdio.

claude mcp add --transport stdio my-database -- npx @modelcontextprotocol/server-postgres postgresql://localhost:5432/mydb

That command registers a stdio MCP server called my-database. When Claude Code starts, it spawns npx @modelcontextprotocol/server-postgres with the connection string as an argument. The server exposes tools for querying the database, and Claude Code discovers them automatically.

HTTP is the recommended transport for remote MCP servers. It uses a streamable HTTP connection where Claude Code sends requests and receives responses over standard HTTP. This is the transport you want for hosted MCP services, shared team servers, or any server that runs on infrastructure you do not manage directly.

claude mcp add --transport http my-remote-server https://mcp.example.com/v1

HTTP transport supports OAuth 2.1 authentication, covered shortly below. It is the direction the ecosystem is moving, and if you are building or choosing MCP servers today, HTTP should be your default for anything remote. For guidance on taking MCP servers from development to reliable infrastructure, our guide on deploying MCP servers to production covers transport selection, containerisation, and operational concerns.

SSE (Server-Sent Events) was the original transport for remote MCP servers. It uses a persistent HTTP connection with server-sent events for streaming responses. As of early 2026, SSE is deprecated in favour of HTTP transport. It still works, and you will find many existing MCP servers that use it, but new implementations should use HTTP. Claude Code treats SSE as a legacy option.

claude mcp add --transport sse my-legacy-server https://mcp.example.com/sse

A typical progression starts with a stdio server for Postgres, which takes about thirty seconds to set up. Next might come an HTTP server for a team's shared knowledge base, which takes slightly longer because it involves OAuth. Then an SSE server for an older monitoring tool that has not yet migrated. All three work from within the same Claude Code session, and Claude can use tools from any of them interchangeably.

MCP Transport Protocol Details from the Specification

The three transports differ in how JSON-RPC 2.0 messages flow across the wire. This reference pulls the core framing and session behaviour straight from the protocol specification.

Transport	Message framing	Session id mechanism	Bidirectional?	Deprecation status
stdio	Newline-delimited JSON on stdout/stdin; server MAY log to stderr	Not applicable (single process pair)	Yes, via stdin and stdout streams	Active
Streamable HTTP	POST of JSON-RPC, response is either JSON or text/event-stream chunks	Mcp-Session-Id HTTP header set by server, echoed by client	Yes, via GET-initiated SSE stream from server	Active, current default for remote
HTTP+SSE (legacy)	POST for requests; persistent GET for server-to-client events	Implementation-defined	Yes, but via two separate endpoints	Deprecated 2025-03-26, retained for back-compat

Data source: Model Context Protocol Transports spec 2025-11-25, as of 2026-04. Permalink: systemprompt.io/guides/claude-code-mcp-servers-extensions#mcp-transport-protocol-details-from-the-specification.

Installing and Managing MCP Servers

The claude mcp command handles all MCP server management. The subcommands are straightforward.

# Add a stdio server
claude mcp add --transport stdio github-mcp -- npx @modelcontextprotocol/server-github

# Add an HTTP server
claude mcp add --transport http analytics-server https://analytics.example.com/mcp

# List all configured servers
claude mcp list

# Get details about a specific server
claude mcp get my-database

# Remove a server
claude mcp remove my-database

You can also set environment variables for a server at registration time. This is useful for servers that need API keys or configuration values.

claude mcp add --transport stdio my-server -e API_KEY=your-api-key-here -e REGION=eu-west-1 -- npx some-mcp-server

Within a running Claude Code session, you can manage MCP servers interactively using the /mcp slash command. This opens a panel showing all connected servers, their status, and available tools. You can restart a server that has crashed, disconnect one you no longer need, or authenticate with a remote server that requires OAuth.

Scopes and Where Configuration Lives

Every MCP server you add has a scope that determines where its configuration is stored and who can see it. This is one of those details that seems minor until you are working in a team and someone asks why their Claude Code session does not have the database server you set up yesterday.

Local scope is the default. When you run claude mcp add, the server configuration is stored in your personal settings for the current project. Nobody else on the team sees it. It does not get committed to version control. This is right for personal tooling, experimental servers, or anything that uses your personal credentials.

Project scope stores the configuration in a .mcp.json file at the root of your project. This file is meant to be committed to version control. Everyone who clones the repository gets the same MCP server configuration.

claude mcp add --scope project shared-db -- npx @modelcontextprotocol/server-postgres $DATABASE_URL

The .mcp.json file looks like this.

{
  "mcpServers": {
    "shared-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "team-api": {
      "type": "http",
      "url": "https://mcp.team-tools.example.com/v1"
    }
  }
}

Notice the ${DATABASE_URL} syntax. Project-scoped servers can reference environment variables without hardcoding secrets. Each developer sets the variable in their own environment, and the .mcp.json file stays safe to commit.

User scope stores the configuration globally for your user account, across all projects. Use this for MCP servers you want available everywhere, like a personal knowledge base or a general-purpose utility server.

claude mcp add --scope user my-notes -- npx @modelcontextprotocol/server-notes ~/notes

Local scope works well for most things. Project scope suits shared team infrastructure. User scope fits the handful of servers you want available in every project regardless of context. The discipline of choosing the right scope saves confusion later.

OAuth Authentication for Remote Servers

Remote MCP servers often require authentication. The HTTP transport supports OAuth natively. When you connect to a server that requires OAuth, Claude Code handles the flow for you.

The first time you use a server that needs authentication, the /mcp command in Claude Code will prompt you to authorise. This opens a browser window with the OAuth consent screen. You authenticate, grant permissions, and the token is stored securely. Subsequent sessions reuse the token until it expires.

This matters because it means you can connect to company-internal MCP servers that sit behind SSO. The server implements OAuth, Claude Code handles the client-side flow, and your existing identity provider handles the rest. No API keys to rotate. No credentials in configuration files.

For servers that use simpler authentication, you can pass tokens as environment variables.

claude mcp add --transport http my-api -e AUTH_TOKEN=your-token-here https://api.example.com/mcp

Plugin-Provided MCP Servers

Some Claude Code plugins bundle their own MCP servers. When you install one of these plugins, the MCP server is managed automatically. It starts when Claude Code starts, stops when Claude Code stops, and updates when the plugin updates.

Plugin-provided MCP servers have access to a CLAUDE_PLUGIN_ROOT environment variable that points to the plugin's installation directory. This lets the server find its configuration files and assets without hardcoded paths.

The lifecycle management is the key advantage here. With a manually configured MCP server, you are responsible for ensuring the server process is running, updating it when new versions are released, and debugging it when it crashes. With a plugin-provided server, the plugin system handles all of that. You install the plugin and the tools appear.

Plugin-provided servers are particularly useful for services that require complex setup. A Kubernetes MCP server, for instance, needs cluster credentials, context configuration, and namespace defaults. Wrapping all of that in a plugin means the setup happens once and works consistently.

Custom Subagents

This is where MCP servers connect to something larger. Claude Code supports custom subagents, which are specialised AI agents that have their own tool access, model selection, and permissions. Subagents let you create focused assistants within your Claude Code environment.

A subagent is defined as a markdown file with YAML frontmatter. You place it in .claude/agents/ for project-specific agents or ~/.claude/agents/ for agents available across all projects. The markdown body becomes the agent's system prompt, and the frontmatter configures its capabilities.

Here is a subagent designed for database work.

---
name: "database-assistant"
description: "Queries and analyses the application database. Use for data questions, schema exploration, and migration planning."
tools:
  - "mcp:shared-db:query"
  - "mcp:shared-db:list_tables"
  - "mcp:shared-db:describe_table"
  - "Read"
model: "sonnet"
permissionMode: "default"
---

You are a database specialist. When asked about data or schema questions, use the database tools to query directly rather than guessing.

Always check the current schema before suggesting migrations. Use `describe_table` to verify column types and constraints.

When writing queries, prefer COUNT and aggregation for overview questions. Only return raw rows when specifically asked.

Never run DELETE, DROP, or TRUNCATE operations. If asked to modify data, write the query but do not execute it. Present it for review instead.

The tools field controls which tools the subagent can access. The mcp:shared-db:query syntax means "the query tool from the MCP server named shared-db". You can also reference built-in tools like Read, Bash, Edit, and Write. If you omit the tools field entirely, the subagent gets access to all available tools.

The model field selects which Claude model the subagent uses. Your options are sonnet, opus, haiku, or inherit. The inherit option uses whatever model the parent session is running.

sonnet works well for most subagents because it is fast and capable. For complex reasoning tasks, opus is the better choice. For high-volume, low-complexity work like code exploration, haiku keeps costs down.

The permissionMode field controls how the subagent handles tool permissions. Valid values are default (same permission rules as the parent session), acceptEdits (auto-accepts file edits but prompts for other tools), dontAsk (never prompts, skips disallowed tools), bypassPermissions (allows all tools without prompting), and plan (read-only mode for planning and analysis).

Other configuration options include hooks (to attach event-driven workflows to the subagent), skills (to reference registered skills the agent can use), and memory (to define persistent context the agent carries between invocations).

You invoke a subagent from Claude Code by referencing it in conversation. Type /agents to see available agents, or simply ask Claude to delegate to a specific agent. Claude Code manages the handoff, passes context, and returns the result to your main conversation.

Built-in Subagents

Claude Code ships with three built-in subagents that cover common patterns. Understanding these helps you design your own.

Explore is a read-only agent that uses the Haiku model. It is designed for codebase exploration, answering questions about project structure, finding relevant files, and summarising code. It cannot modify files or run commands. Because it uses Haiku, it is fast and inexpensive. It works especially well for orientation in unfamiliar codebases.

Plan is a read-only agent that inherits the parent model. It reads files and analyses code but cannot make changes. It is designed for planning work, creating implementation outlines, and identifying dependencies. The inherited model means it gets the same reasoning power as your main session.

The general-purpose subagent inherits the parent model and has access to all tools. This is the default delegation target when Claude Code decides it needs to break a task into subtasks. It can read, write, execute, and call any configured MCP server. It is essentially a fresh Claude Code session scoped to a specific task.

The recommended pattern is to use the built-in agents for general work and create custom subagents for specialised domains. A database assistant only sees database tools. A documentation agent only sees file reading and writing tools. A deployment agent only sees infrastructure tools. The narrower the tool access, the more focused and reliable the subagent becomes.

MCP Tool Search

As you add more MCP servers, the number of available tools grows. A Postgres server might expose five tools. A GitHub server might expose twenty. A Kubernetes server might expose thirty. Connect all three and you have fifty-five tools competing for space in Claude's context window.

Claude Code handles this with an automatic tool search mechanism. When the total number of available tools exceeds roughly ten percent of the context window, Claude Code activates tool search. Instead of loading every tool description into the context, it loads a search index. When Claude needs a tool, it searches the index first, then loads the relevant tool descriptions on demand.

This is transparent to you as a user. You do not need to configure anything. But it is worth knowing about because it affects how you name and describe your MCP server tools.

Clear, descriptive tool names and descriptions make the search more effective. If your custom MCP server has a tool called do_thing, Claude will struggle to find it. If it is called query_user_signups_by_date_range, Claude finds it immediately. When building your own MCP server, invest time in naming tools clearly from the start.

This becomes apparent quickly with generic tool names like fetch, update, and list. Claude often picks the wrong tool because the names are ambiguous. Renaming them to fetch_customer_record, update_billing_address, and list_recent_orders fixes the problem entirely.

MCP Capabilities Supported by Claude Code

The Model Context Protocol defines five server-side capability areas. Claude Code does not consume all of them. Knowing which are live matters when you evaluate an MCP server and find it exposes resources or prompts that never appear in the session.

Capability	Server declares	Claude Code consumes	Typical use
Tools (tools/list, tools/call)	Yes	Yes	Callable functions such as query, create_issue, deploy_service
Resources (resources/list, resources/read)	Yes	Yes	Read-only context such as schemas, files, or API docs
Prompts (prompts/list, prompts/get)	Yes	Yes (surfaced via slash commands)	Reusable templated prompts the user can invoke
Completions (completion/complete)	Yes (argument autocompletion)	Yes (in-session arg hints)	Suggests values for tool or prompt arguments
Roots (roots/list)	Client-side feature	Yes (exposes workspace dirs to servers)	Lets servers know which directories are in scope
Sampling (sampling/createMessage)	Client must implement	Not implemented in Claude Code as of the 2025-11-25 spec	Would let servers ask the model for completions
Elicitation (elicitation/create)	Client must implement	Not implemented in Claude Code as of the 2025-11-25 spec	Would let servers prompt the user for structured input

Data source: Model Context Protocol base specification 2025-11-25 and Claude Code MCP docs, as of 2026-04. Permalink: systemprompt.io/guides/claude-code-mcp-servers-extensions#mcp-capabilities-supported-by-claude-code.

Popular MCP Servers Inventory

These are the servers most commonly installed in Claude Code setups, taken from the reference list maintained by the Model Context Protocol project and the wider community registry. Install commands are the ones published on the server's own repository.

Server	Source repository	Transport	Install command	Primary use
Filesystem	modelcontextprotocol/servers	stdio	npx -y @modelcontextprotocol/server-filesystem /path/to/dir	Scoped file read/write outside the project root
Git	modelcontextprotocol/servers	stdio	uvx mcp-server-git --repository /path/to/repo	Local git history and diff tools
Fetch	modelcontextprotocol/servers	stdio	uvx mcp-server-fetch	Fetch and convert web pages to markdown
Memory	modelcontextprotocol/servers	stdio	npx -y @modelcontextprotocol/server-memory	Knowledge-graph scratch memory for the session
Sequential Thinking	modelcontextprotocol/servers	stdio	npx -y @modelcontextprotocol/server-sequential-thinking	Stepwise reasoning scaffold
GitHub	github/github-mcp-server	Streamable HTTP	claude mcp add --transport http github https://api.githubcopilot.com/mcp/	Issues, PRs, file content, search across GitHub
Slack	Community (various)	stdio	npx -y @modelcontextprotocol/server-slack	Read channels, post messages with a bot token
Supabase	supabase-community/supabase-mcp	stdio	npx -y @supabase/mcp-server-supabase --access-token <token>	Database schema, SQL, and edge-function access

Data source: modelcontextprotocol/servers reference list, GitHub MCP server repository, Supabase MCP server repository, as of 2026-04. Permalink: systemprompt.io/guides/claude-code-mcp-servers-extensions#popular-mcp-servers-inventory.

Enterprise MCP Management

For organisations running Claude Code across development teams, managing MCP servers at scale requires more than individual configuration. Claude Code provides enterprise-grade controls through managed settings that let administrators define which MCP servers are available, required, or prohibited.

The managed-mcp.json file is the enterprise configuration surface. Administrators deploy this file to control MCP server availability across the organisation. It sits alongside the managed settings file and follows a similar structure.

{
  "mcpServers": {
    "company-knowledge-base": {
      "type": "http",
      "url": "https://kb.internal.example.com/mcp",
      "description": "Internal knowledge base and documentation search"
    },
    "approved-database": {
      "type": "stdio",
      "command": "npx",
      "args": ["@company/db-mcp-server"],
      "env": {
        "DB_HOST": "readonly-replica.internal.example.com"
      }
    }
  }
}

The managed MCP servers appear automatically in every developer's Claude Code session. Developers cannot remove or modify them. They can add their own servers alongside the managed ones, unless the administrator restricts that.

For granular control, administrators can use allowedMcpServers and deniedMcpServers lists. The allowed list acts as an allowlist: only servers whose names match can be added. The denied list acts as a denylist: servers whose names match are blocked.

These use pattern matching, so you can allow company-* to permit any server with the company prefix while blocking everything else. To lock down the environment completely, set allowedMcpServers to an empty array, which prevents developers from adding any MCP servers beyond the managed configuration.

{
  "allowedMcpServers": ["company-*", "approved-*"],
  "deniedMcpServers": ["*-experimental"]
}

This layered approach means you can mandate certain servers (via managed-mcp.json), allow a curated set of additional servers (via allowedMcpServers), and block specific known-bad patterns (via deniedMcpServers). The combination covers most enterprise governance requirements without being so restrictive that developers cannot work effectively.

Security Considerations

MCP servers that make network requests introduce a security surface. A malicious or misconfigured MCP server could exfiltrate data, connect to unintended services, or make requests that violate network policies. For a detailed treatment of authentication and security patterns, see the guide on MCP server authentication and security.

The combination of managed MCP servers, allowedMcpServers, and deniedMcpServers gives administrators layered control. They know exactly which MCP servers are running and exactly which tools those servers expose.

For additional protection, scope each MCP server's credentials to the minimum required access. A database MCP server should connect to a read-only replica, not the primary. An API MCP server should use a token with the narrowest possible permissions.

For compliance-heavy industries, this level of control is not optional. For everyone else, it is still good practice. The full details of enterprise lockdown are covered in the managed settings guide.

Putting It All Together

Here is the MCP setup we use daily at systemprompt.io. This is a real configuration, not a contrived example.

The .mcp.json (project scope, committed to the repository) looks like this.

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

Local-scope servers (not committed) include a GitHub MCP server with a personal access token and a file search server configured for the monorepo structure.

Three custom subagents live in .claude/agents/.

The database-assistant (shown earlier) handles all data queries and migration planning. It uses Sonnet and only has access to database tools.

A review-agent that reads code and runs analysis but cannot modify anything. It uses the inherited model and has Read, Glob, Grep, and Bash tools. Its system prompt instructs it to focus on code quality, security issues, and architectural concerns.

A deploy-agent that has access to our infrastructure MCP server and can check deployment status, view logs, and trigger staging deployments. It uses Sonnet and has strict permissions. Its system prompt prohibits production deployments and requires confirmation for any mutating operation.

Each agent has a clear boundary. The database assistant does not know about deployments. The deploy agent does not see the database. The review agent cannot change anything. This separation makes each agent more reliable because it cannot be confused by tools outside its domain.

We also use hooks alongside MCP servers. A PostToolUse hook logs every MCP tool invocation to a local file, providing an audit trail of what was queried and when. A PreToolUse hook on the deploy agent requires confirmation for any tool call that contains the word "production" in its arguments.

Transport Comparison at a Glance

The choice of transport is one of the first decisions for any MCP server, and the trade-offs are easy to forget once a setup is running. This table summarises the practical differences.

Aspect	stdio	HTTP	SSE (deprecated)
Runs where	Local child process	Remote service	Remote service
Best for	Personal tools, local databases, file-system access	Team servers, hosted SaaS, OAuth-protected services	Legacy servers awaiting migration
Authentication	Environment variables	OAuth 2.1 or bearer tokens	Bearer tokens
Network required	No	Yes	Yes
Process lifecycle	Managed by Claude Code	Managed by the hosting provider	Managed by the hosting provider
Startup cost	Spawns on every Claude Code launch	None (already running)	None (already running)
Debugging	Run the command in a terminal to see stderr	Inspect HTTP logs on the server	Inspect HTTP logs on the server
Recommended in 2026	Yes, for anything local	Yes, the default for anything remote	No, migrate to HTTP

A good default is to pick stdio for everything on your machine and HTTP for everything else. SSE should only appear if an upstream vendor has not yet shipped HTTP support, and you should treat those servers as interim.

Worked Example: Postgres MCP Server from Zero to Connected

Most MCP setups start the same way. A developer wants Claude Code to read from a local Postgres database without shelling out to psql or copy-pasting query results. Here is the full sequence, with the exact commands and the checkpoints that matter.

Step 1. Verify Postgres is reachable. Before adding any MCP server, confirm the connection string works from the shell.

psql "postgresql://localhost:5432/mydb" -c "select 1"

If that fails, the MCP server will fail with the same error. Fix the connection string first, not the Claude Code configuration.

Step 2. Register the server with local scope. For personal use, local scope keeps the configuration out of version control.

claude mcp add --transport stdio project-db \
  -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost:5432/mydb

The -y flag on npx accepts the package install prompt so the command does not hang the first time it runs. This is a common reason a stdio server appears to do nothing on the first launch.

Step 3. Verify the server is visible. Run claude mcp list and look for project-db with a connected status. If the status is disconnected, run the raw command in a terminal to see the error output directly.

Step 4. Move to project scope once it works. When you are ready to share the server with the team, convert local scope to project scope by editing .mcp.json and using an environment variable for the connection string.

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

Each developer then exports DATABASE_URL in their own shell profile. The file commits cleanly.

Step 5. Ask Claude a real question. Open Claude Code in the project and ask something the database can answer directly, for example "how many orders were created in the last seven days?" Claude should discover the query tool and run a SELECT COUNT(*). If it does not, use the /mcp slash command to inspect the tool list.

This five-step loop works for any stdio MCP server. Replace the package name and the connection string, and the pattern is the same for GitHub, Linear, Slack, or a custom server you built in-house. If Step 5 works but subsequent queries are slow, the server is likely re-establishing the database connection on each tool call. Check whether the server implementation uses a connection pool. Most community Postgres MCP servers pool by default, but custom servers often skip this.

Troubleshooting Common MCP Issues

MCP servers occasionally fail to connect or behave unexpectedly. These are the most common issues and how to resolve them.

Server fails to start. Run claude mcp list and check the server status. If it shows as disconnected, the server process likely crashed on startup. Run the server command manually in a terminal (for example, npx @modelcontextprotocol/server-postgres postgresql://localhost:5432/mydb) to see the error output directly. Missing dependencies and incorrect connection strings are the usual culprits.

Tools not appearing. If a server shows as connected but its tools do not appear, restart it with the /mcp slash command in Claude Code. If tools still do not appear, the server may not be declaring them correctly. Use claude mcp get <server-name> to inspect the tool list.

Permission prompts reappearing. Claude Code remembers your tool approval choices per project. If you want to reset these choices and start fresh, run claude mcp reset-project-choices. This is useful when you have denied a tool by mistake or when a server has updated its tool definitions.

OAuth token expired. For HTTP servers using OAuth, an expired token causes authentication failures. Open the /mcp panel in Claude Code and re-authenticate with the affected server. The OAuth flow will refresh your token.

Server crashes mid-session. If a server crashes during a conversation, Claude Code will show an error when it tries to use that server's tools. Use the /mcp command to restart the server without leaving your session. Your conversation context is preserved.

allowedMcpServers blocking legitimate servers. If the managed settings define an allowlist and you add a server whose name does not match a pattern, Claude Code silently refuses to start it. There is no loud error, just a missing tool. Always check claude mcp list after adding a new server in a managed environment. If the server is not listed, read the current allowedMcpServers patterns and either rename the server to match or ask an administrator to expand the list.

stdio servers hang on first launch. Servers installed through npx sometimes block on the package install prompt. The symptom is a server stuck in connecting status for more than ten seconds. The fix is to add the -y flag to the npx invocation so the prompt auto-accepts. If you are managing the server through a .mcp.json file, put -y in the args array before the package name.

Tools overlap between servers. If two MCP servers expose tools with the same name, Claude Code disambiguates by prefixing the server name. You may see github:search and gitlab:search instead of a plain search. This is a feature, not a bug, but it can trip up subagents whose tool lists were written before the second server was added. Update the tools frontmatter to use the prefixed form when this happens.

Common Pitfalls to Avoid

A few patterns cause more friction than any other, and they all have simple fixes once you know to look for them.

Connecting everything at once. The temptation when setting up a new environment is to add every MCP server that sounds useful. Resist it. Every extra server widens the tool surface Claude has to reason about, increases the chance of ambiguous tool selection, and adds to your token consumption since tool definitions occupy context space. For techniques on managing these costs, see our guide on Claude Code cost optimisation. Start with one server, measure the value, and then add the next. A good rule is to add a new server only when you have a specific task that fails without it.

Using production credentials for local development. It is easy to point a local MCP server at a production database, especially when you are in a hurry. Do not. Connect to a read-only replica, a staging copy, or a seeded development database. The same Claude Code session that lets you query data also lets it write queries, and a misinterpreted prompt against a production database is a recovery incident you do not want.

Hardcoding secrets in .mcp.json. The ${VARIABLE_NAME} syntax exists for a reason. Any secret committed to version control has to be rotated the moment someone notices, and the moment someone notices may be weeks after the commit lands. Use environment variables, document the required variables in the project README, and keep .mcp.json free of credentials.

Skipping scope planning. Adding a server with default scope and then wondering why teammates cannot see it is the single most common source of support questions. Decide the scope before running claude mcp add. For personal tooling, local scope. For team infrastructure, project scope. For cross-project utilities, user scope. The five seconds of thought saves a lot of debugging.

Forgetting to restart after config changes. Editing .mcp.json directly does not affect the currently running Claude Code session. Neither does changing an environment variable referenced by a server. Restart Claude Code, or at minimum use /mcp to disconnect and reconnect the affected server, after any configuration change.

Neglecting tool descriptions in custom servers. When building your own MCP server, the description field on each tool is not documentation for humans. It is the primary signal Claude uses to decide which tool to call. A tool described as "runs a query" competes poorly against fifty other tools. A tool described as "executes a read-only SQL query against the analytics database and returns rows as JSON arrays" gives Claude unambiguous selection criteria. Invest the same care in tool descriptions that you would invest in function names. If Claude consistently picks the wrong tool, the description is almost always the cause. Rewriting a single description from vague to specific often fixes the selection problem entirely without any changes to the tool's implementation.

The Lesson

MCP servers transform Claude Code from a code assistant into a development environment that can interact with your entire technology stack. But the real lesson is not about the technology. It is about boundaries.

The most effective MCP setups share three characteristics. They are specific in scope. They have clear permissions. They separate concerns through subagents.

The least effective setups connect everything to everything. Every MCP server available to every conversation, every tool accessible from every context. That approach leads to confused tool selection, accidental data access, and security blind spots.

Start with one MCP server that solves a real friction point. For most developers, that is a database server or a project management tool. Get comfortable with how it integrates into your workflow. Then add a second. Then consider whether a custom subagent would help focus the interaction.

For enterprise teams, invest in the managed configuration early. Setting up managed-mcp.json before developers start adding their own servers is far easier than retroactively locking things down. The enterprise managed settings guide covers the full configuration surface.

The Model Context Protocol is an open standard with a growing server registry. The ecosystem of available servers is expanding rapidly. As of early 2026, there are community servers for most major databases, cloud providers, communication tools, and development platforms. The official MCP documentation maintains a registry of available servers, and the subagents documentation covers the full configuration surface for custom agents.

Conclusion

This guide began with a three-pane terminal setup. Database in one, Claude Code in another, documentation in a third. That setup still works. But it is no longer how we work.

Our current setup is a single Claude Code session with MCP servers connected to the database, the project management tool, and the infrastructure. Custom subagents handle specialised tasks. Hooks log everything and enforce policies.

The result is not just more efficient. It is more coherent. Every interaction happens within the same context, and Claude can draw connections between a database query result, a code change, and a deployment status without manually bridging the gaps.

The Model Context Protocol is the layer that makes this possible. Not because the technology is particularly complex (it is a fairly straightforward client-server protocol) but because it standardises the interface between AI and tools. That standardisation means you set up the connection once and every future conversation benefits from it.

Connect your first MCP server today. The claude mcp add command takes thirty seconds. The productivity difference compounds from the first session.