Claude Architect · 강의

프로젝트 범위와 사용자 범위

VCS에 공유되는 .mcp.json과 개인용 ~/.claude.json을 비교합니다

프로젝트 범위와 사용자 범위은(는) CoddyKit의 무료 Claude Architect 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Claude Architect 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Claude Architect 강의에는 총 4개의 강의가 포함되어 있습니다.

이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.

Two Homes for MCP Config

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.

What an MCP Server Provides

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: .mcp.json in VCS

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.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Secrets Never Get Committed

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.

# Each developer exports their own token locally
export GITHUB_TOKEN="ghp_yourPersonalTokenHere"

# .mcp.json references it as ${GITHUB_TOKEN} — the
# literal token value is NEVER written into the repo

User Scope: ~/.claude.json

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.

{
  "mcpServers": {
    "my-notes": {
      "command": "node",
      "args": ["/Users/me/tools/notes-mcp/server.js"]
    }
  }
}

The Mental Model: Mirror of CLAUDE.md

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 Onboarding Test

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.

Prefer Community Servers Over Custom

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.

Resources Shine in Project Scope

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.

{
  "mcpServers": {
    "db-schema": {
      "command": "npx",
      "args": ["-y", "@acme/mcp-schema-server"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Structured Errors Survive Either Scope

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.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Upstream timeout contacting issues API",
  "attempted_query": "list_issues(repo='acme/web')",
  "partial_results": []
}

A Practical Split

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.

Quick Check: Choosing Scope

Apply the decision rule to a real scenario.

Recap: Project vs User Scope

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.

자주 묻는 질문

“프로젝트 범위와 사용자 범위” 강의는 무료인가요?

네 — “프로젝트 범위와 사용자 범위” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Claude Architect 강의 전체를 잠금 해제할 수 있습니다. Claude Architect 강의에는 총 4개의 강의가 포함되어 있습니다.

“프로젝트 범위와 사용자 범위”에서 뭘 배우나요?

VCS에 공유되는 .mcp.json과 개인용 ~/.claude.json을 비교합니다 브라우저에서 직접 실행하는 실습 코드로 Claude Architect을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Claude Architect을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Claude Architect은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.

“프로젝트 범위와 사용자 범위” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Claude Architect 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Claude Architect 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Claude Architect(으)로 돌아가기