Область проекта и область пользователя

When you wire an MCP server into Claude Code, the server definition has to live somewhere. There are two scopes, and choosing the wrong one is a classic architecture mistake.

• Project scope — .mcp.json at the repo root, committed to version control. Shared with the whole team.
• User scope — ~/.claude.json in your home directory. Personal, never shared via VCS.

The decision rule is simple: does everyone working on this repo need this server? If yes, it belongs in project scope.

Before scoping, recall what you're actually sharing. An MCP server exposes three primitive types:

• Tools — actions the model can invoke (query a DB, open a ticket).
• Resources — read-only data and context, like schemas or catalogs.
• Prompts — reusable templates.

When you commit a server to .mcp.json, every teammate instantly gets the same Tools, Resources, and Prompts — a shared, reproducible capability surface.

Project scope is the right home for servers the whole team relies on: the company's GitHub server, an internal database gateway, a shared design-system resource server.

Because .mcp.json is committed, a new teammate clones the repo and the tooling is already there — no manual setup, no "works on my machine" drift.

Sharing a server config is fine. Sharing a token is a breach. The rule: reference secrets through environment variables — never commit the raw value.

In .mcp.json you write ${GITHUB_TOKEN}, which expands from each developer's own environment at runtime. The shared file describes how to connect; each machine supplies its own credential.

User scope lives in ~/.claude.json and is personal to you. It is the right place for servers that are yours and would only get in a teammate's way if shared:

• A personal notes / second-brain server.
• An experimental server you're evaluating.
• A workflow tool tied to your individual accounts.

Crucially, user scope is not shared via VCS — new teammates never receive it.

This scope split mirrors the CLAUDE.md hierarchy exactly — same principle, different file:

• Project-level (./CLAUDE.md, .mcp.json) — shared via VCS, everyone gets it.
• User-level (~/.claude/CLAUDE.md, ~/.claude.json) — personal, NOT shared, so new teammates miss it.

Same logic governs .claude/skills/ and .claude/commands/: project scope is shared via VCS, the ~/.claude/ copies are personal.

The sharpest way to decide scope: ask "When a new teammate clones this repo, should this just work?"

• Yes → project scope (.mcp.json). They clone, the server is configured, they're productive on day one.
• No, this is mine → user scope (~/.claude.json).

Put a team-critical server in user scope and you've created an invisible dependency: it works for you, silently fails for everyone else, and nobody knows why.

For standard integrations — GitHub, Slack, Postgres, filesystem — prefer a community MCP server over building your own. Less code to maintain, well-tested behavior, and it drops cleanly into project scope.

Reserve custom servers for genuinely proprietary systems where no community option exists. Whatever you choose, the scoping decision is the same: team-wide → .mcp.json; personal → ~/.claude.json.

An MCP Resource exposes read-only context — a DB schema, an API catalog, a coding-standards doc. These are exactly the things a team wants identical across every developer.

Ship a schema-exposing server in .mcp.json and every teammate's Claude sees the same authoritative schema. No one queries against a stale mental model, and answers stay consistent across the team.

Scope governs where the server is defined, not how robust it is. A well-built MCP server returns structured errors regardless of scope: an isError flag plus an errorCategory (transient / validation / business / permission), isRetryable, a message, the attempted query, and any partial results.

Generic errors like "Operation failed" block intelligent recovery; structured ones let the agent route, retry, or escalate. Design this into the server — it pays off whether shared or personal.

A realistic setup combines both scopes cleanly:

• Project (.mcp.json, committed): GitHub server, internal DB gateway, schema resource server — everything the team needs to build this product.
• User (~/.claude.json, private): your personal notes server, an experimental tool you're trialing.

The two layers compose: Claude Code loads both, giving you the shared team surface plus your personal extras — without polluting the repo or leaking your private tooling onto teammates.

Apply the decision rule to a real scenario.

Key takeaways:

• Project scope = .mcp.json, committed to VCS, shared with the whole team. Use it when everyone needs the server on clone.
• User scope = ~/.claude.json, personal, NOT shared via VCS. Use it for your private or experimental servers.
• Mirrors the CLAUDE.md hierarchy: project-level is shared, user-level is personal and missed by new teammates.
• Never commit secrets — reference them via env vars like ${GITHUB_TOKEN}.
• Prefer community servers for standard integrations; design structured errors regardless of scope.

Decision rule to remember: should a new teammate get this on clone? Yes → project. Mine → user.