Claude Architect · 강의

환경 변수로 비밀 값 관리하기

${GITHUB_TOKEN}을 참조하고 토큰은 절대 커밋하지 않습니다

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

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

Why Secrets Don't Belong in Config

MCP servers connect Claude to real systems — GitHub, databases, internal APIs. Each connection needs credentials: tokens, API keys, passwords.

The architect's rule is absolute: secrets never live in committed files. Your .mcp.json (project scope, shared in version control) declares which servers exist and how to launch them — but a raw token written there is now in your git history forever.

The clean pattern is to reference a secret by environment-variable name and let the runtime resolve it. This lesson shows how MCP does exactly that with ${GITHUB_TOKEN}.

The Two MCP Scopes

MCP configuration lives in two distinct scopes, and the distinction drives where secrets are safe:

Project scope — .mcp.json at the repo root. Shared via VCS so the whole team gets the same servers.
User scope — ~/.claude.json. Personal, on your machine only, NOT shared.

Because project scope is committed, anything you put in .mcp.json is visible to everyone with repo access — including a leaked clone. That is precisely why a token's value must never appear there; only a reference to an env var may.

Referencing a Secret with ${VAR}

In .mcp.json you pass credentials through the server's env block, using ${VAR} expansion. The literal text ${GITHUB_TOKEN} is committed safely — the real token is resolved from the environment at launch time.

Here the GitHub MCP server receives its token without the secret ever touching the file.

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

Where the Real Value Comes From

The reference ${GITHUB_TOKEN} is inert until the runtime supplies the actual value. You provide it through your shell environment — typically from a local, git-ignored .env file or your OS secret store.

The token is set outside the repo. The committed config stays clean; each developer (and each CI runner) injects their own value.

# .env — git-ignored, never committed
export GITHUB_TOKEN="ghp_realSecretValueLivesOnlyHere"

# load it into the shell before launching Claude Code
source .env

Lock the Door: .gitignore

Referencing an env var is only half the defense. You must also guarantee the file holding the real value never gets committed.

Add your secret files to .gitignore. Commit an example file with placeholder names so teammates know which variables to set — without ever shipping the values.

# .gitignore
.env
.env.local
*.secret

# .env.example  (THIS one is committed — names only, no values)
GITHUB_TOKEN=
DATABASE_URL=

Personal vs Shared Secrets

Scope also decides whose credential is used:

A shared service token the whole team uses can be referenced in project .mcp.json — each member still supplies the value via their own environment.
A purely personal token (your individual PAT) fits naturally with user scope ~/.claude.json, which isn't shared anyway.

Either way the principle holds: the file may contain the name; the environment supplies the value. Never invert that.

Prefer Community MCP Servers

For standard integrations — GitHub, Postgres, Slack, filesystem — prefer a maintained community MCP server over a custom one. They already implement the env-based secret handling correctly, expose proper Tools/Resources/Prompts, and return structured errors.

Writing your own server just to call GitHub means re-implementing auth and token handling you could inherit safely. Reserve custom servers for genuinely proprietary systems.

Secrets in CI/CD

In a pipeline there is no developer .env to source. Instead, your CI platform's encrypted secret store injects the variable into the job environment, and the same ${GITHUB_TOKEN} reference resolves identically.

This is why the reference pattern matters: one committed .mcp.json works locally and in CI, with the value sourced differently in each place — and never printed.

# GitHub Actions — value comes from encrypted repo secrets
jobs:
  review:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - run: claude -p "/review" --output-format json

Least Privilege for Tokens

An MCP token inherits whatever permissions you granted it. A GitHub PAT scoped to repo can push code; one scoped to read:org cannot.

Mirror the architect's least-privilege habit from tool and subagent design: grant each token only the scopes its server actually needs. If ${GITHUB_TOKEN} ever leaks despite your safeguards, a tightly scoped, short-lived token limits the blast radius dramatically.

Rotation and Leak Response

Treat any committed secret as compromised — even after you delete it, it remains in git history. The only real fix is to revoke and rotate the credential at its source (GitHub settings), then re-issue a fresh one into your environment.

Because your config references ${GITHUB_TOKEN} rather than embedding a value, rotation is painless: revoke the old token, update the env var, relaunch. No code change, no commit.

# After rotating the token at the provider, just update the env value:
export GITHUB_TOKEN="ghp_freshlyRotatedValue"
# .mcp.json still references ${GITHUB_TOKEN} — nothing else changes

Putting It Together

The complete, exam-grade pattern for MCP secrets:

Declare the server in project .mcp.json (shared via VCS).
Reference the secret as ${GITHUB_TOKEN} in the env block — never the raw value.
Supply the value from a git-ignored .env locally and from an encrypted store in CI.
Ignore secret files; commit only an .env.example of names.
Scope tokens to least privilege and rotate on any suspicion.

Config is shareable; secrets are not. That separation is the whole game.

Quick Check: Sharing an MCP Config

Apply the secret-handling rules to a real team scenario.

Recap: Secrets with Environment Variables

Key takeaways:

MCP config has two scopes: project .mcp.json (shared via VCS) and user ~/.claude.json (personal).
Committed config may hold a reference like ${GITHUB_TOKEN} — never the token value.
Real values come from a git-ignored .env locally and an encrypted secret store in CI; commit only an .env.example of names.
Prefer community MCP servers — they handle env-based secrets correctly out of the box.
Scope tokens to least privilege; on any leak, revoke and rotate at the source — the reference pattern makes rotation a one-line env change.

Separate the shareable from the secret, and you've internalized the rule the exam is testing.

자주 묻는 질문

“환경 변수로 비밀 값 관리하기” 강의는 무료인가요?

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

“환경 변수로 비밀 값 관리하기”에서 뭘 배우나요?

${GITHUB_TOKEN}을 참조하고 토큰은 절대 커밋하지 않습니다 브라우저에서 직접 실행하는 실습 코드로 Claude Architect을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

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

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

“환경 변수로 비밀 값 관리하기” 강의는 얼마나 걸리나요?

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

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

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

이 강의의 모든 강의

← Claude Architect(으)로 돌아가기