MCP: wiring in your own tools

The signal that you need it

You keep copying things into the chat. A stack trace out of Sentry. A ticket out of Jira. A row out of the database. Every paste is context you had to fetch by hand, and it is stale the moment you paste it.

MCP (Model Context Protocol) is an open standard for connecting an agent to external tools and data. Claude Code speaks it, so anything with an MCP server — and most of the tools you already use have one — becomes something Claude can read and act on directly.

01 · Three kinds of server

02 · Adding one

A local server runs a command. Everything after -- is passed to that command untouched:

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

A remote one just takes a URL:

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

With a token, if the service uses one rather than OAuth:

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

03 · Scope: who gets this server

The flag that decides whether this is yours, this project's, or the team's.

claude mcp add --transport http shared-server --scope project https://example.com/mcp

04 · The committed file

Project-scoped servers land in .mcp.json at the repo root, so a teammate who clones the project gets the same tooling:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "database-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "DB_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

05 · Logging in

Most hosted servers use OAuth. Add the server, then authenticate from inside a session:

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

/mcp

That opens the browser login flow. From the shell, claude mcp login sentry does the same, and claude mcp logout sentry clears the credentials again.

06 · How the tools show up

Once connected, the server's tools appear under a predictable name:

mcp__<server-name>__<tool-name>

# a `query` tool from a server named `database`
mcp__database__query

Which matters, because that name is what you write in permission rules, in a skill's allowed-tools, in a subagent's tool list, and in hook matchers. A matcher of mcp__database__.* catches everything that server exposes.

So the guardrails you already know apply here unchanged: an MCP tool is just another tool call, and a PreToolUse hook can deny it like any other.

07 · Managing them

claude mcp list              # everything configured
claude mcp get notion        # details for one
claude mcp remove notion     # disconnect it
claude mcp add-from-claude-desktop   # import what you already set up

/mcp inside a session shows live connection status, which is the first thing to check when a tool silently is not there.

08 · The part to be careful about

An MCP server decides what content enters Claude's context. That makes a server you do not control a genuine attack surface, not a theoretical one.

• Trust the server before you connect it. A server that fetches external content can feed instructions into your session — this is prompt injection, and the agent has your permissions.
• Project-scoped servers ask for approval before first use, because they arrive in a file someone else can commit.
• headersHelper runs a shell command on your machine to produce auth headers. Read it before you approve it.
• Scope narrowly. A read-only database server is a very different risk from one that can write.

Verified against the official Claude Code documentation, September 2026. Claude Code moves quickly, so check the official documentation before relying on a detail here.

What's next