Claude Code MCP: add, scope, and debug MCP servers.

To add an MCP server to Claude Code, run claude mcp add <name> -- <command> for a local server or claude mcp add --transport http <name> <url> for a remote one. By default it applies only to the current project. Add -s user to use it everywhere, or -s project to write it to a shared .mcp.json. Run claude mcp list to check it connects.

Book a demo

Here to connect Claude Code to a database? Read Connect Claude Code to your database, or jump to the worked example.

CLI

The claude mcp commands.

Without --transport, Claude Code assumes stdio. Put Claude Code's own flags before the server name and the server's command after --, so flags like -y reach the server and not Claude Code.

claude mcp add <name> -- <command> [args]	Add a local stdio server. Everything after -- is the command Claude Code starts.
claude mcp add <name> -e KEY=value -- <command>	Same, with environment variables for the server process. Repeat -e for more.
claude mcp add --transport http <name> <url>	Add a remote streamable HTTP server. Use this for hosted servers and for local servers that listen on a port.
claude mcp add --transport http <name> <url> -H "Authorization: Bearer ..."	Add an HTTP server that needs a header, such as an API key. Repeat -H for more headers.
claude mcp add -s project ...	Pick the scope: local (default), project, or user. See the scopes table below.
claude mcp add-json <name> '<json>'	Add a server from a JSON config, the same shape as one entry in .mcp.json.
claude mcp add-from-claude-desktop	Import the servers you already set up in Claude Desktop (macOS and WSL).
claude mcp list	List configured servers and check that each one connects.
claude mcp get <name>	Show one server's config and status.
claude mcp remove <name>	Delete a server. Add -s to pick the scope if the name exists in more than one.
claude mcp login <name>	Run the OAuth sign-in for a remote server. logout clears it.
claude mcp reset-project-choices	Forget which .mcp.json servers you approved or rejected in this project.
/mcp	Inside a Claude Code session: see each server's status, sign in to OAuth servers, turn servers off.

Terminal

# stdio: Claude Code starts the server as a local process
$ claude mcp add airtable -e AIRTABLE_API_KEY=key -- npx -y airtable-mcp-server

# HTTP: Claude Code connects to a URL, for every project
$ claude mcp add --transport http -s user sentry https://mcp.sentry.dev/mcp

$ claude mcp list

SSE (--transport sse) still works for older servers, but it's deprecated. Use HTTP when a server offers both.

Local, project, or user scope.

The scope decides where the server is saved and who gets it. Most "my server disappeared" problems are a server added in local scope in a different folder.

Scope	Saved in	Who gets it
local	~/.claude.json, under the current project	Only you, only in this project. The default.
project	.mcp.json in the project root	Everyone who clones the repo. Commit the file.
user	~/.claude.json	Only you, in every project.

If the same name is in more than one scope, local wins over project, and project wins over user.

Teams

Share servers with .mcp.json.

A .mcp.json in the repo root gives everyone on the project the same servers. Reference secrets as ${VAR} so each person's key stays in their own shell, and use ${VAR:-default} for a fallback.

.mcp.json

JSON

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

Approved once per person.

Claude Code doesn't start servers from a cloned repo on its own. The first time you run claude in the folder, it asks you to approve them. Until then they show as pending.

Variables expand in these fields.

command, args, and env for stdio servers, url and headers for HTTP servers.

Stop the permission prompt for trusted tools.

Claude Code asks before each MCP tool call until you allow it. MCP tools are named mcp__<server>__<tool>. Allow one tool, or the whole server with mcp__<server>. Read-only tools are the safe ones to allow first.

Project settings

JSON

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "mcp__sentry",
      "mcp__valv-desktop__query"
    ]
  }
}

When an MCP server doesn't work in Claude Code.

Start with claude mcp list, which shows each server as connected, failed, needing sign-in, or pending approval. Then /mcp in a session.

The server isn't in claude mcp list	It was added in another scope or another project. Local scope only applies to the folder you ran the command in. Re-add it with -s user to use it everywhere.
⏸ Pending approval	Servers from a project's .mcp.json need your OK once. Start claude in that folder and approve them, or run claude mcp reset-project-choices if you rejected one by mistake.
A stdio server fails to start on Windows	On native Windows, npx needs a wrapper: claude mcp add <name> -- cmd /c npx -y <package>.
A stdio server times out at startup	The first npx or uvx run downloads the package. Install it first, or start Claude Code with a longer startup timeout, for example MCP_TIMEOUT=10000 claude (milliseconds).
! Needs authentication	The server uses OAuth. Run /mcp in a session and pick the server, or claude mcp login <name> from your shell.
Large tool output gets cut off	Claude Code warns above 10,000 tokens of tool output and caps it at 25,000 by default. Raise the cap with MAX_MCP_OUTPUT_TOKENS, or ask for less data per call.
${API_KEY} shows up literally, or a warning about a missing variable	Variables in .mcp.json are read from the shell that starts claude. Export them first, or give a fallback with ${VAR:-default}.
Valv: ✘ Failed to connect on 127.0.0.1:4319	Valv Desktop isn't open, or it picked another port because 4319 was taken. Copy the command from Settings, MCP Server again.
Valv: Claude Code sees the wrong data, or none	Claude Code works against the workspace that is active in Valv. Switch to the workspace that holds your database.

Worked example

Connect Claude Code to a database through Valv's MCP server.

Valv Desktop runs a local HTTP MCP server while the app is open. It holds the database connection, so Claude Code only gets a URL and read-only tools, never the password.

1

Add your database in Valv.

Connect Postgres, MySQL, SQLite, ClickHouse, MongoDB, or a folder of Excel and CSV files. Hide any table or column Claude Code shouldn't see in the AI access tab.
2
Copy the Claude Code command.

Open Settings, MCP Server, and expand Claude Code. Port 4319 is the default. If it's taken, Valv uses another port, so copy the command the app shows. Add -s user to use it in every project.
```
claude mcp add --transport http valv-desktop http://127.0.0.1:4319/mcp
```
3
Or share it in .mcp.json.

Everyone on the team who runs Valv gets the same entry. No token is needed for a local agent.
```
{
  "mcpServers": {
    "valv-desktop": {
      "type": "http",
      "url": "http://127.0.0.1:4319/mcp"
    }
  }
}
```
4

Ask in Claude Code.

Keep Valv open and start claude. It works against whichever workspace is active in Valv, and reads Valv's server instructions on how to use the tools.

Tools Claude Code gets from Valv

list_datasources

Databases and remote MCP servers in the active workspace.

list_resources · describe_resource

Tables and their columns, minus anything hidden in AI access.

query

A structured, read-only query that Valv validates before it runs.

run_code

Several read queries chained in one step.

remember

Proposes a fact for workspace memory. You confirm it in Valv.

read_file · write_file · edit_file

Dashboards and other files in the workspace folder.

run_flow · set_flow_enabled · notify

Test and turn on scheduled checks, send a notification.

In Claude Code they show up as mcp__valv-desktop__query and so on. With more than one datasource, data tools get a prefix such as app__query.

claude

> Which features did accounts that churned last month stop using?

tool  list_datasources
tool  describe_resource   events
tool  query               account_id, event, created_at

A table of features by drop-off, with the
query object in each tool call.

> Save that as a dashboard.

An illustration of the flow, not a recorded session. Tool names and columns depend on your schema. The dashboard is a file in the Valv workspace, not a change to the database.

You can also run Claude Code inside Valv, with tables and charts next to the chat. That setup, and how Valv keeps Claude Code read-only, is in Connect Claude Code to your database. Using Codex too? The Codex MCP guide covers its commands and config.toml.

Which MCP server to add for what.

Valv is one option for data. It isn't the right pick for everything.

Your team's tools

Issue trackers, error monitoring, and docs usually ship a hosted HTTP server. One claude mcp add --transport http and a sign-in through /mcp.

Raw SQL and tuning

If Claude Code should run EXPLAIN, suggest indexes, or write migrations, a standalone database server fits better. Valv doesn't run raw SQL. The Postgres MCP guide compares the options.

Read-only data answers

Valv, when Claude Code should answer questions from your product data without write access or your password. See the database MCP guide for other clients.

Claude Code MCP, answered

How do I add an MCP server to Claude Code?

Run claude mcp add <name> -- <command> for a local stdio server, or claude mcp add --transport http <name> <url> for a remote one. Check it with claude mcp list, or /mcp inside a Claude Code session.

Where does Claude Code store MCP servers?

Local and user scoped servers live in ~/.claude.json. Project scoped servers live in .mcp.json in the project root, so you can commit them and share them with your team. Local is the default scope.

What is the difference between local, project, and user scope?

Local: only you, only in the current project. Project: everyone who uses the repo, stored in .mcp.json. User: only you, in every project. If the same name exists in more than one scope, local wins over project, and project wins over user.

How do I share MCP servers with my team in Claude Code?

Add them with -s project, or write a .mcp.json file in the project root and commit it. Keep secrets out of it with ${VAR} references. Each teammate approves the project's servers once the first time they start claude in that folder.

How do I stop Claude Code asking for permission on every MCP tool call?

Allow the tools in .claude/settings.json under permissions.allow. MCP tools are named mcp__<server>__<tool>. mcp__<server> allows every tool from that server.

Can I use my Claude Desktop MCP servers in Claude Code?

Yes, on macOS and WSL. Run claude mcp add-from-claude-desktop and pick the servers to import.

Can Claude Code query my database over MCP?

Yes. With Valv Desktop open, run claude mcp add --transport http valv-desktop http://127.0.0.1:4319/mcp. Claude Code can then list, describe, and query the tables in Valv's active workspace with read-only tools, and it never receives your database password.

Give Claude Code your database over MCP.

Free for personal use, every feature included. Commercial use needs a seat at beta pricing. See pricing.

All downloads Other platforms and builds