MCP Servers in Claude Code: Connect Databases and Tools

MCP servers give an AI coding agent access to things outside your repository, such as a database, an issue tracker or an internal API. In Claude Code you add one with claude mcp add and choose whether it is private to you or shared with the team through a .mcp.json file. Claude can then call that server's tools the same way it calls its built-in ones. This guide covers how that works, the commands you need, and the settings that matter once you have more than one or two servers.

What an MCP server actually is

The Model Context Protocol (MCP) is described by its maintainers as "an open-source standard for connecting AI applications to external systems." An application that supports MCP can connect to data sources (local files, databases), tools (search engines, calculators) and workflows (specialized prompts).

A server can expose three kinds of things to Claude Code:

• Tools: functions Claude can call, such as "run this query" or "create an issue". In Claude Code their full names look like mcp__<server>__<tool>.
• Resources: data you pull into a prompt with an @ mention, for example @github:issue://123 or @postgres:schema://users.
• Prompts: workflows that appear as commands. Claude Code lists them as /servername:promptname (MCP), and you can also type the long form, for example /mcp__github__pr_review 456.

Because the protocol is open, one server can work with many clients. The MCP project lists Claude, ChatGPT, Visual Studio Code and Cursor among the clients that support it. Each client has its own configuration format, so the commands below apply only to Claude Code.

Remote and local servers

Remote HTTP servers run elsewhere and you reach them by URL. Claude Code's documentation recommends HTTP for remote servers:

claude mcp add --transport http notion https://mcp.notion.com/mcp

If the server takes a static token, pass it as a header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

The older SSE transport is deprecated. Claude Code tries HTTP first and switches to SSE when a server does not accept it; that automatic switch needs v2.1.265 or later. On older versions, pass --transport sse for SSE-only servers.

Local stdio servers are programs Claude Code starts on your machine. The -- separates Claude Code's own options (--transport, --env, --scope) from the command that runs the server, and everything after it is passed to the server untouched:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Claude Code sets CLAUDE_PROJECT_DIR in a stdio server's environment to the project root, so a local server can tell which project it is working in.

For browsers, Claude Code also has a built-in Claude in Chrome server, which admin controls treat separately (see the security section below).

Scopes: who gets the server

Every server has a scope, set with --scope. It decides who sees the server and where it is stored:

# Shared with everyone who clones the repo
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# Available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

If the same name is defined in more than one place, precedence is local, then project, then user, then plugin-provided servers, then claude.ai connectors. A server an organization provides through the managedMcpServers managed setting ranks above all of these. The winning entry is used whole; fields are not merged across scopes.

A sensible split: project for servers the whole team needs on this codebase, user for personal tools you want everywhere, and local for experiments or anything holding your own credentials.

The .mcp.json file and keeping secrets out of git

A project-scoped server is written to .mcp.json, which you commit:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Do not commit real tokens here. Use environment variable expansion: ${VAR} reads a variable, and ${VAR:-default} falls back to a default when it is unset. Expansion works in command, args, env, url and headers:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Two details catch people out:

• An unset variable with no default is left as the literal ${VAR} text. The config still loads, and Claude Code reports a missing-variable warning.
• In a remote server's url and headers, certain credential variables always read as empty, and a :-default on them is ignored. Examples include ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY and NPM_TOKEN. If a server needs one of those values, copy it into a variable with your own name.

For short-lived tokens or SSO, headersHelper runs a command that prints a JSON object of headers. It runs fresh on each connection, is not cached, and is abandoned after 10 seconds. If a tool call returns 401 or 403, Claude Code re-runs the helper and retries the call once.

Authentication with OAuth

Many hosted servers use OAuth instead of static tokens. Add the server, then sign in:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Inside Claude Code, run /mcp and complete the browser login. From the shell:

claude mcp login sentry
claude mcp login sentry --no-browser   # print the URL instead of opening a browser

claude mcp login prints the URL on its own when no local browser is available, which helps over SSH. claude mcp logout <name> clears stored credentials. If a server needs a pre-registered redirect URI, fix the port with --callback-port. claude -p and Agent SDK runs cannot run the OAuth flow, so sign in from an interactive session first. Removing a remote server also deletes the OAuth tokens and client registration stored for it.

Managing and debugging servers

claude mcp list              # all servers and their status
claude mcp get notion        # details for one server
claude mcp remove notion     # remove it

claude mcp list shows states such as ✔ Connected, ! Needs authentication, ✘ Failed to connect and ⏸ Pending approval. Inside a session, /mcp lets you sign in, turn a server off without losing its configuration, and reconnect it; /mcp reconnect all retries every failed server.

If a slow server will not start, raise the startup timeout (in milliseconds):

MCP_TIMEOUT=10000 claude

A "timeout" field in a server's .mcp.json entry sets that server's tool timeout in milliseconds and overrides MCP_TOOL_TIMEOUT for it.

If you already set servers up in Claude Desktop, claude mcp add-from-claude-desktop imports them on macOS and WSL. In the other direction, claude mcp serve runs Claude Code itself as a stdio MCP server for other clients.

Context, output limits and tool search

Every tool definition costs context. Claude Code handles this with tool search, on by default on supported models: only tool names and server instructions load at session start, and full definitions load when Claude needs them. You can tune it with ENABLE_TOOL_SEARCH:

ENABLE_TOOL_SEARCH=auto:5 claude   # load upfront while definitions total under 5% of context
ENABLE_TOOL_SEARCH=false claude    # load everything upfront

Claude Code turns tool search off when ANTHROPIC_BASE_URL points to a non-first-party host, because most proxies do not forward the blocks it needs; setting ENABLE_TOOL_SEARCH explicitly overrides that.

To keep a server's tools always visible, set "alwaysLoad": true on it. Each upfront tool uses context, and startup waits for that server's tools (up to the 5-second connect timeout), so reserve this for the few tools Claude needs on every turn.

Tool output is capped as well. Claude Code warns when a tool returns more than 10,000 tokens, and the default maximum is 25,000 tokens. You can raise it:

MAX_MCP_OUTPUT_TOKENS=50000 claude

Separately, a successful text result longer than 50,000 characters is saved to a file and replaced with a file reference, whatever MAX_MCP_OUTPUT_TOKENS is set to. Database servers hit these limits most, because a full schema or large query result easily goes over. A server author can raise the threshold for one tool, such as get_schema, with the anthropic/maxResultSizeChars annotation, up to 500,000 characters.

Security: approval, prompt injection and team controls

The documentation says to verify you trust each server before connecting it, and warns that servers fetching external content can expose you to prompt injection. A server can read data and act on your behalf, so review it as you would a new dependency.

Built-in safeguards:

• Project servers need approval. In interactive sessions, Claude Code asks before using servers from a cloned .mcp.json. Reset those choices with claude mcp reset-project-choices.
• Headless runs do not ask. In claude -p, Agent SDK and cloud sessions, project servers load without a prompt. To block one, add it to disabledMcpjsonServers in settings. This matters if you run Claude Code in CI.
• Per-tool approval. A server author can mark a tool with anthropic/requiresUserInteraction so it prompts on every call, even in acceptEdits, auto and bypassPermissions modes. In dontAsk mode the call is denied.

For organizations, administrators can control MCP centrally:

• A managed-mcp.json file at a system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, C:\Program Files\ClaudeCode\ on Windows) takes exclusive control. Users cannot add or use other servers, including plugin servers. An empty mcpServers map blocks every server except the few that still load under exclusive control.
• allowedMcpServers and deniedMcpServers in managed settings filter what users configure. Match on serverUrl or serverCommand. The docs say a serverName entry "is not a security control", because a user can call any server github.
• With managed-mcp.json deployed, Claude in Chrome is blocked in terminal sessions unless allowClaudeInChromeWithManagedMcp is set in the device's own managed settings.

Where to start

Add one remote server over HTTP, sign in with /mcp, and check claude mcp list before adding more. Put team-wide servers in .mcp.json with ${VAR} placeholders, and keep personal credentials in local or user scope. Leave tool search on, and raise output limits only for servers that need it, which usually means databases. Before anything runs unattended, decide which project servers a headless run may load. A CLAUDE.md file is a good place to tell the agent when to use each server.

For more on running several Claude Code sessions as a team, see the Atlas home page.