Progress will not be saved. This browser is blocking storage (often private browsing). You can still learn, but closing the tab loses your progress.
Practice needs JavaScript. The reading works without it.Back to the reading
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.
.mcp.json sits at the repo root and looks like this:
{
"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.jsonbefore using it. Until then,claude mcp listshows⏸ Pending approval. If you said no by mistake, runclaude mcp reset-project-choicesto be asked again. - A repo can't approve its own servers: approval settings committed in
.claude/settings.jsonare ignored until you trust the folder. - On the other hand,
claude -pand the Agent SDK can't ask, so they load project servers straight away. Runningclaude -pin an unfamiliar repo lets that repo's servers run. To block a server, add it todisabledMcpjsonServersin your settings.
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.
"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 listwarnsMissing environment variables: GITHUB_PAT, and the server can't connect. - The value isn't shown:
claude mcp get githubdisplays the header asBearer ${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_KEYorNPM_TOKEN, always read as empty when sent to a remote server. That's how Claude Code stops an unfamiliar.mcp.jsonfrom stealing your keys. Use a name of your own, likeGITHUB_PAT.
GitHub runs an official remote MCP server at https://api.githubcopilot.com/mcp/, authenticated with a personal access token. The steps:
- Open
github.com/settings/personal-access-tokensand create a fine-grained token for only the repos you need. If Claude should only read, grant read access only. - Put the token in an environment variable in your shell, not in the repo:Terminal
export GITHUB_PAT=github_pat_... - 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}" } } } } - Start
claudein that folder, approve the server when asked, then type/mcp. Thegithubrow 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.
Once connected, you ask Claude in plain words:
Summarise the open issues in app-works-247/todo-api, one line eachWhen 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.
- Check status:
/mcpin a session, orclaude mcp listin your terminal. - Switch one off for now without deleting its config: select it in
/mcpand 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 githubshows 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.