What you need to know
Where a server is configured decides who gets it
| Scope | File | Shared? | Use for |
|---|---|---|---|
| Project | .mcp.json in the repository | Yes, through version control | Team tooling: the issue tracker, the shared GitHub server |
| User | ~/.claude.json | No, only you | Personal or experimental servers |
A server in the project file reaches every teammate and every CI runner on clone, with no per-machine setup to drift. An experimental server in the project file reaches everyone too, which is usually not what you want.
Keep secrets out of the repository
Project configuration is committed, so it must not contain tokens. .mcp.json supports environment variable expansion:
{"mcpServers": {
"github": {
"command": "github-mcp-server",
"env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
}}}Each developer (and the CI system) sets GITHUB_TOKEN in their own environment.
All servers' tools are available at once
Tools from every configured MCP server are discovered when the agent connects and are available together, alongside the built-in tools. That is convenient, and it is also why tool count and description quality (lessons 2.1 and 2.3) matter.
Make MCP tools win when they should
An agent often prefers a built-in like Grep over a more capable MCP tool, such as a semantic code search, because the MCP tool's description does not explain what it can do. The fix is a richer description of capabilities and outputs, and of when to prefer it over Grep.
Build or reuse
For standard integrations (Jira, GitHub, common databases), prefer an existing community MCP server over writing your own. Reserve custom servers for team-specific workflows nobody else has built.
Resources for catalogues
Agents waste calls exploring: listing collections, probing schemas, checking which categories exist. An MCP resource exposes such a catalogue (a documentation hierarchy, a database schema, a list of issue summaries) as content the agent can read directly, so it knows what is available without exploratory tool calls.
In the exam
Look for: a server that teammates need but cannot see (it is in the user file), a personal server leaking to the team (it is in the project file), a token in the repo, an MCP tool losing to Grep, or agents burning calls on discovery. The answers are scope, ${VAR} expansion, better descriptions and resources.
Check your understanding
The team needs a shared GitHub MCP server that requires a personal access token. Where and how do you configure it?
Show answer
Answer: B. Project scope shares the server with everyone through version control; environment variable expansion keeps each person's token out of the repository.
Subagents spend a third of their calls listing document collections and probing schemas. What reduces this most?
Show answer
Answer: A. Resources give agents a readable catalogue of what exists, so they stop making exploratory calls to find out.
Which TWO belong in your user-level configuration rather than the project's .mcp.json? Select TWO.
Show answer
Answer: B, D. User scope is for personal and experimental servers that should not reach teammates. Anything the team or CI depends on belongs in the project file.
Apply it: Lakeshore's MCP setup
Lakeshore's agent needs the community issue-tracker server and the in-house portside-graph server, and one engineer wants to try a new profiling server.
- Place each server in the right scope and say why.
- Write the project
.mcp.jsonentry for the issue tracker, keeping its API token out of the repository. - Fix the Grep preference by writing a description for
portside-graph's search tool. - Choose one catalogue to expose as a resource and say which exploratory calls it removes.
Show model answer
1. Scopes. Issue tracker and portside-graph: project .mcp.json, because every engineer and the CI agent use them. Profiling server: the engineer's ~/.claude.json, because it is an experiment.
2. Entry
{"mcpServers": {"tracker": {"command": "tracker-mcp",
"env": {"TRACKER_TOKEN": "${TRACKER_TOKEN}"}}}}3. Description. "Semantic search over Portside's code graph: finds classes and methods by meaning and relationship (callers, implementations, dependencies), including through interfaces and re-exports. Returns symbols with file and line. Prefer this for structural questions; use Grep for literal strings such as error messages."
4. Resource. A module catalogue: each Portside module, its purpose, owners and main entry points. It removes the agent's habit of listing directories and opening README files to find out what exists.