MCP

A file called .mcp.json at the root of your project, one top-level key called mcpServers, and one object under it per server. That is the entire configuration surface. Everything else in this module is either a field inside one of those objects or a consequence of what the server hands back once it connects.

A server here is usually a small program running on your own computer, started by Claude Code when the session opens, rather than a machine in a data centre somewhere. It offers Claude a set of tools. The rules those programs follow when they talk to Claude Code are the Model Context Protocol, MCP, and a protocol is an agreed format two programs use to understand each other. One format, so one server works under any tool that speaks it.

A server object is one of two shapes. A local process, which Claude Code starts itself and talks to by writing to the program’s input and reading its output, needs command and usually args and env. A remote endpoint, which Claude Code reaches across the network over HTTP, needs url and usually headers. The type field says which. Get type wrong and the other fields are read against the wrong set of expected keys, which is the first thing to check when a server refuses to connect.

The file, and the three other places its tools show up

---
description: Pull open issues and group them by area.
allowed-tools: mcp__github__list_issues
---

List the open issues, then group them by the area of the
codebase they touch.

---
name: triager
description: Reads GitHub issues. Writes nothing.
tools: mcp__github__list_issues
---

You read issues and report. You do not open, close, or
comment on anything.

{
"permissions": {
  "allow": ["mcp__github__list_issues"],
  "deny": ["mcp__postgres"]
}
}

{
"mcpServers": {
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/",
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  },
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL:-postgres://localhost/dev}"
    }
  }
}
}

The four server types

The route the messages travel is called the transport, and type is where you name it. stdio is short for standard input and output, the two streams every program already has for reading text in and printing text out. The other three send the messages over a network instead.

stdio is the default when you add a server from the command line without saying otherwise. sse is deprecated, meaning it still works but is on its way out, and you will still meet it, because servers that shipped against it have not all moved. streamable-http is accepted as another name for http, which matters more than it sounds: it is the name the MCP specification uses, so a config block copied out of a server’s own documentation works unmodified.

ws has one wrinkle worth knowing before it costs you an afternoon. It has no --transport ws path in the documented add table, so you write it in JSON by hand, and it does not appear in claude mcp list at all. Check it with claude mcp get <name> or the /mcp panel.

Expansion

Write ${VAR} in this file and Claude Code swaps in the value your shell holds for that name before the server starts. Swapping a name for its value like that is expansion. ${VAR} and ${VAR:-default} both work, in command, args, env, url, and headers. That is what makes a committed .mcp.json safe to share: the file names the variable, and each developer’s shell supplies the value. A ${VAR} with no value and no :-default produces a startup warning rather than a silent empty string, so a missing token announces itself.

Three scopes, and the one you commit

A server’s scope is how far it reaches: which projects it loads in, and whether anyone else on your team gets it.

Project is the scope this course cares about, because it is the only one that travels with the repo. Local is the default, which means a server you add without thinking about scope lands somewhere your teammates will never see.

Scope is fixed when you add a server. Changing it is a remove and a re-add:

# stdio, project scope. Everything after -- is the command.
claude mcp add --scope project postgres -- npx -y @modelcontextprotocol/server-postgres

# remote, with a static token instead of OAuth
claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_TOKEN"

# moving a server from local to project scope
claude mcp remove github --scope local

When the same server name appears in more than one place, the order is local, then project, then user, then plugin-provided, then claude.ai connectors. First one found wins.

The naming rule

A server called github exposing a tool called list_issues appears at runtime as:

mcp__github__list_issues

Two underscores between each part. That string, in full, is what you write in every place Claude Code asks you to name a tool:

A server shipped inside a plugin gets a longer form, because the plugin name is folded in to keep two plugins from colliding:

mcp__plugin_<plugin-name>_<server-name>__<tool-name>

Any character outside A-Za-z0-9_- becomes an underscore. And the server itself registers under a third spelling, plugin:<plugin>:<server>, which is what you write where a server rather than a tool is expected, such as the server field of an mcp_tool hook. Three spellings of one thing is a lot to hold, so the practical move is to open /mcp, read the tool names off the panel, and copy them.

Resources and prompts

Tools are the loudest part of MCP and not the only part.

A server can expose resources, which you pull into a prompt with an @ reference shaped @server:protocol://path, where the middle word names the kind of thing you are asking for. @github:issue://123, @postgres:schema://users, @docs:file://api/authentication. Type @ and the list is fuzzy-searchable. Referenced resources are fetched and attached for you, and you can put several in one prompt.

A server can also expose prompts, which surface as slash commands named /mcp__<server>__<prompt>. A server called code-helper with a prompt called explain gives you /mcp__code-helper__explain. Names normalise to underscores, same as tools.

Limits worth knowing before you hit them

Everything a server returns has to fit in the same context the rest of your conversation lives in. Models count that text in tokens, the small chunks they read text as, each one shorter than a word. MAX_MCP_OUTPUT_TOKENS defaults to 25,000, and a warning fires once a single result crosses 10,000 tokens. Server startup times out at 30,000 ms by default, adjustable with MCP_TIMEOUT.

Tool search is on by default, so a session starts by loading tool names and server instructions only, and fetches the full description of each tool’s arguments when a tool is actually reached for. Tool descriptions and server instructions are each truncated at 2 KB. A server that must be loaded upfront regardless sets alwaysLoad: true.

Check yourself

1. Your .mcp.json says "type": "streamable-http". Does the server load?
2. You add a server with claude mcp add and no --scope. Your teammate clones the repo. Do they get it?
3. A hook matcher reads postgres. The server is called postgres and exposes query. How many times does the hook fire?