MCP servers in Claude Code: setup, scopes, and security

Adding a server

Two shapes. A local stdio server is a process on your machine and everything after the -- is the command that runs it. A remote server is a URL and needs an explicit --transport.

# local stdio server: just me, just this project (the default scope)
claude mcp add db -- npx -y @bytebase/dbhub --dsn "$READONLY_DATABASE_URL"

# the whole team, written to a committed .mcp.json
claude mcp add --transport http --scope project linear https://mcp.linear.app/mcp

# me, in every project
claude mcp add --transport http --scope user sentry https://mcp.sentry.dev/mcp

# a server that needs a header credential
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_PAT"

# a transport --transport does not accept (ws), via JSON
claude mcp add-json events \
  '{"type":"ws","url":"wss://mcp.example.com/socket"}'

Keep credentials out of the committed file

.mcp.json supports environment expansion, so a shared config can reference a secret each developer supplies themselves. Both ${VAR} and ${VAR:-default} work, in command, args, env, url, and headers.

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${READONLY_DATABASE_URL}"]
    },
    "docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://mcp.example.com/v1}"
    }
  }
}

The security model, stated plainly

Claude Code has a permission system that governs what the agent does directly: which files it may edit, which commands it may run. That system does not extend through an MCP server.

1. Scope the credential, not the prompt. Give the database server a read-only role. That is a boundary; an instruction is not.
2. Read the server code, or at least know who wrote it. A stdio server runs as you, with your files and your network.
3. Prefer project scope for shared servers, so additions arrive in a pull request rather than each person quietly adding their own.
4. Deny the tools you never want. MCP permission rules use the server name: mcp__puppeteer matches every tool on that server, mcp__puppeteer__puppeteer_navigate matches one.
5. Be careful with anything that fetches external content. Anthropic’s own docs flag this: a server that pulls arbitrary URLs turns outside content into a possible instruction channel.
6. Audit periodically. claude mcp list. Servers accumulate and nobody removes them.

{
  "permissions": {
    "deny": [
      "mcp__puppeteer",
      "mcp__db__execute_sql"
    ],
    "allow": [
      "mcp__db__query"
    ]
  }
}

Debugging a server that will not connect

# configured servers plus a health status each
claude mcp list

# one server in full
claude mcp get sentry

# from inside a session: tool counts, disable toggle, OAuth
/mcp

npx -y @bytebase/dbhub --dsn "$READONLY_DATABASE_URL"

# raise the 30s startup timeout while you investigate
MCP_TIMEOUT=60000 claude

Timeouts, output limits, and the context question

MCP has more clocks than most people realise, and a slow server hits a different one depending on how it is failing.

Tool search changed the token maths

For a long time the honest advice was that every connected server contributed its tool definitions to context on every turn, so servers you forgot about were a permanent tax. As of August 2026 that is no longer the default. Tool search is on by default: only tool names and server instructions load at session start, and full schemas load when Claude searches for them.

• Add servers for work you actually do repeatedly, not for capability you might want.
• Prefer local or user scope for personal experiments so you do not impose them on the team.
• Write real server instructions if you author a server. With tool search on, that text is how Claude decides to go looking for your tools. Descriptions and instructions are truncated at 2KB each.

Sharing servers with a team

Project scope is the point at which MCP stops being a personal convenience and becomes shared infrastructure, which means it needs the same review as code.

Questions people ask

Keep reading