HowToCodePage

Connecting external tools with MCP servers

Add local and remote Model Context Protocol servers, control who can see them, and understand the context and trust cost of every tool you enable.

Adding a server

MCP is the protocol that exposes outside capabilities - a database, an issue tracker, a browser - to the agent as tools and resources. Claude Code speaks it as a client, so one server works with any MCP-capable host.

# a local process spoken to over stdio
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://localhost:5432/app"

# a remote server over HTTP
claude mcp add --transport http linear https://mcp.linear.app/mcp

# see what is connected, and which scope owns it
claude mcp list
claude mcp get postgres

# inside a session
/mcp
ScopeStored inVisible to
localYour user config for this projectOnly you, only here
project.mcp.json at the repo rootEveryone who clones the repo
userYour user config, every projectOnly you, everywhere

Project-scoped servers and secrets

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}
  • .mcp.json is committed, so it must never contain a literal credential - reference environment variables with ${VAR} syntax instead.
  • Each developer exports their own token; the file stays shareable.
  • Remote servers authenticate over OAuth in most hosted offerings, which prompts once and stores the token outside the repository.
⚠️
A tool produced by an MCP server returns text that goes straight into your context. A compromised or careless server can therefore inject instructions, leak data it was given, or quietly disagree with your review. Enable the servers you need, read what scopes the token grants, and never grant write access to a server you have not read the tool list for.

Context cost and allowlisting

Every connected server contributes its tool definitions to the system prompt on every turn, whether or not you use them. Three servers with twenty tools each is a permanent tax on the whole session, and it also makes tool selection harder for the model.

{
  "permissions": {
    "allow": [
      "mcp__github__get_pull_request",
      "mcp__github__list_issues",
      "mcp__postgres__query"
    ],
    "deny": [
      "mcp__github__delete_*",
      "mcp__postgres__execute"
    ]
  }
}
  • MCP tools are named mcp__<server>__<tool>, which is exactly how you allow or deny them.
  • Deny beats allow, so an explicit deny for destructive operations is worth more than a long allow list.
  • Disconnect servers you are not using this week - claude mcp remove is reversible.
  • Prefer one server that does a job well over four that overlap; overlapping tools cause the agent to pick the wrong one.

FAQ

Is it safe to add a third-party MCP server?
The server sees whatever the tools it exposes can reach, and its output enters your context. Treat it like any dependency: check who publishes it, what scopes its credentials need, and prefer read-only tokens. For servers you cannot audit, deny the write tools explicitly.
Why is my session suddenly so expensive?
Tool definitions from newly added MCP servers are prepended to every request. Measure with /context before and after adding servers; if the jump is large, remove the ones you are not actively using.

Permissions and safety with agents Skills, plugins and marketplaces

Last refreshed 2026-09-18.