Lesson 5.218 min · 5 cards · 8 exercises · 1 mission

.mcp.json and scopes

Share MCP servers with the team through .mcp.json, keep tokens in environment variables, and connect GitHub so Claude can read issues.

In lesson 5.1 you connected a server with claude mcp add, and it existed only on your machine. But what if the whole team needs the same GitHub server? Everyone types the command themselves, picks their own name, and sooner or later someone picks a different one. This lesson puts the server configuration in the repo with a .mcp.json file, keeps the token out of the repo, and connects GitHub so Claude can read todo-api's issues.

Three places a server can live

Each server is saved at one of three scopes:

Scope Available in Shared with the team Stored in
local (default) This project only No ~/.claude.json
project This project only Yes, through git .mcp.json at the repo root
user All your projects No ~/.claude.json

Pick by asking "who needs this server, and where":

  • local: a server you're trying out, or one with credentials you don't want in git.
  • project: a server the whole team needs for this repo. That's this lesson's scope.
  • user: personal tools you use in every project, like the docs server from lesson 5.1.

Don't confuse MCP's "local" with the .claude/settings.local.json file: local servers live in ~/.claude.json in your home folder, not in the repo.

If the same server name exists in several places, Claude Code uses one definition, in this order of priority: local, then project, then user, then plugins, and finally claude.ai connectors. Fields are not merged: if the local entry wins, the whole project entry is ignored. To change a server's scope, remove it and add it again at the new scope.

The .mcp.json file

.mcp.json sits at the repo root and looks like this:

JSON
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

An HTTP server needs type and url; a stdio server needs command and args. You can write the file by hand, or run claude mcp add … --scope project and let Claude Code create and update it. Claude Code reads .mcp.json when a session starts, so after editing it, start a new session.

Because the file travels with the repo, everyone who clones it gets it, including clones of a stranger's repo. Claude Code handles that like this:

  • In an interactive session, Claude Code asks you to approve each server in .mcp.json before using it. Until then, claude mcp list shows ⏸ Pending approval. If you said no by mistake, run claude mcp reset-project-choices to be asked again.
  • A repo can't approve its own servers: approval settings committed in .claude/settings.json are ignored until you trust the folder.
  • On the other hand, claude -p and the Agent SDK can't ask, so they load project servers straight away. Running claude -p in an unfamiliar repo lets that repo's servers run. To block a server, add it to disabledMcpjsonServers in your settings.

The token never goes in the repo

The GitHub server needs a token. That token must never sit in .mcp.json, because the file gets committed. The right way is an environment variable: the file holds only the variable's name, and the value lives in each person's shell.

JSON
"headers": {
  "Authorization": "Bearer ${GITHUB_PAT}"
}

Claude Code replaces ${GITHUB_PAT} with the variable's value when it connects. Variables work in command, args, env, url and headers. There's also ${VAR:-default} for a fallback when the variable isn't set.

Three things we confirmed when we tried it:

  • Forget to set the variable: the config still loads, but claude mcp list warns Missing environment variables: GITHUB_PAT, and the server can't connect.
  • The value isn't shown: claude mcp get github displays the header as Bearer ${GITHUB_PAT}, by name rather than the real token. A shared screenshot stays safe.
  • Some names are off limits: variables holding Claude Code's or your provider's own credentials, such as ANTHROPIC_API_KEY or NPM_TOKEN, always read as empty when sent to a remote server. That's how Claude Code stops an unfamiliar .mcp.json from stealing your keys. Use a name of your own, like GITHUB_PAT.

Connecting GitHub

GitHub runs an official remote MCP server at https://api.githubcopilot.com/mcp/, authenticated with a personal access token. The steps:

  1. Open github.com/settings/personal-access-tokens and create a fine-grained token for only the repos you need. If Claude should only read, grant read access only.
  2. Put the token in an environment variable in your shell, not in the repo:
    Terminal
    export GITHUB_PAT=github_pat_...
  3. Add the server to todo-api's .mcp.json:
    JSON
    {
      "mcpServers": {
        "github": {
          "type": "http",
          "url": "https://api.githubcopilot.com/mcp/",
          "headers": {
            "Authorization": "Bearer ${GITHUB_PAT}"
          }
        }
      }
    }
  4. Start claude in that folder, approve the server when asked, then type /mcp. The github row should show a ✔. If you see ✘ with a 401 error, the token is wrong, expired, or has no access to the repo.

The docs also give a quick route for solo use: claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer …". That stores the token in ~/.claude.json at local scope, outside the repo. Note that claude mcp add doesn't check the token: a wrong one is saved anyway and only fails when it connects.

Working with GitHub

Once connected, you ask Claude in plain words:

Summarise the open issues in app-works-247/todo-api, one line each

When we tried it, Claude used tool search to find the issue tools, called mcp__github__list_issues, and answered. It returned exactly the three open issues in todo-api, one line each with their labels: two bugs (deleting twice returns 500, broken JSON returns 500) and an enhancement adding a ?done= filter. These are the jobs you'll hand to Claude in later lessons. Some other requests from the docs:

  • "Review PR #456 and suggest improvements"
  • "Create a new issue for the bug we just found"
  • "Show me all open PRs assigned to me"

The last two need a token with write access. With a read-only token, Claude can read but creating an issue will fail. That's a good thing when you're starting out: lesson 5.3 looks closely at how much access is enough.

Putting it together with earlier lessons: an issue describes the bug, the pr-review skill holds the checklist, the debugger subagent fixes it in its own worktree. Now Claude can read the input to that whole workflow without you copying anything by hand.

Managing servers day to day

  • Check status: /mcp in a session, or claude mcp list in your terminal.
  • Switch one off for now without deleting its config: select it in /mcp and turn it off. The choice is saved for that project only, in ~/.claude.json, without touching the team's .mcp.json.
  • See one server's details: claude mcp get github shows its scope, status, URL and headers (by variable name).
  • Remove: claude mcp remove github. For a server in .mcp.json, delete it from the file and commit.

A short rule for the team: .mcp.json says which servers, environment variables keep the secrets, /mcp checks it all works. A newcomer just clones the repo, sets their own variable, approves the servers once, and has the same tools as everyone else.

Practice lesson 5.2

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.