MCP Auth Template

실습용 MCP 템플릿입니다.

이 프로젝트는 두 가지 목적을 같이 다룹니다.

• HTTP 기반 MCP 서버에서 인증이 어떻게 붙는지 연습
• stdio 기반 MCP 서버를 Codex 같은 로컬 MCP 클라이언트에 연결

현재 포함된 기능은 최소 구성입니다.

• GET /healthz
• POST /mcp with Bearer token
• stdio MCP entrypoint
• hello tool 1개

구성

핵심 파일은 아래와 같습니다.

• src/mcp-server.js
  • 공통 MCP 서버 정의
  • hello tool 등록
• src/server.js
  • HTTP MCP 서버
  • /healthz
  • /mcp Bearer 인증
• src/stdio.js
  • stdio MCP 서버
  • Codex 같은 로컬 클라이언트용

툴을 추가하는 방법은 별도 문서로 분리했습니다.

• docs/ADDING_TOOLS.md
• docs/AUTH_SERVER_UPGRADE.md

빠른 시작

1. 설치

npm install

2. 환경 변수 준비

cp .env.example .env

기본값은 아래와 같습니다.

PORT=3000
HOST=127.0.0.1
MCP_BEARER_TOKEN=dev-token

실행 방식

HTTP 서버 실행

npm start

또는:

npm run start:http

실행 후:

• health check: http://127.0.0.1:3000/healthz
• MCP endpoint: http://127.0.0.1:3000/mcp

stdio 서버 실행

npm run start:stdio

이 방식은 포트를 열지 않습니다. 로컬 MCP 클라이언트가 프로세스를 직접 실행해서 stdin/stdout으로 통신합니다.

Transport 차이

HTTP

• 네가 직접 서버를 띄워야 함
• Authorization: Bearer <token> 필요
• 인증 연습에 적합

stdio

• MCP 클라이언트가 서버 프로세스를 직접 실행
• 포트 불필요
• Codex 연결에 적합
• HTTP Bearer 인증은 사용하지 않음

중요한 차이:

• HTTP: 네가 서버를 먼저 실행
• stdio: Codex가 필요할 때 서버를 실행

HTTP 인증

/mcp 요청은 모두 아래 헤더가 필요합니다.

Authorization: Bearer dev-token

값은 .env의 MCP_BEARER_TOKEN으로 변경할 수 있습니다.

인증 실패 시:

• 401 Unauthorized
• WWW-Authenticate 헤더 반환

HTTP MCP 실습 예제

1. Health check

curl -i http://127.0.0.1:3000/healthz

2. initialize

curl -i \
  -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer dev-token' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "0.1.0"
      }
    }
  }'

응답 헤더의 Mcp-Session-Id 값을 다음 요청에 재사용합니다.

3. initialized notification

curl -i \
  -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer dev-token' \
  -H 'Mcp-Session-Id: <session-id>' \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }'

4. tools/list

curl -i \
  -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer dev-token' \
  -H 'Mcp-Session-Id: <session-id>' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

5. hello tool 호출

curl -i \
  -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer dev-token' \
  -H 'Mcp-Session-Id: <session-id>' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "hello",
      "arguments": {
        "name": "MCP"
      }
    }
  }'

예상 응답 예시:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Hello, MCP! This response came from a authenticated HTTP MCP tool at 2026-03-18T05:06:22.258Z."
      }
    ],
    "structuredContent": {
      "greeting": "Hello, MCP!",
      "accessMode": "http",
      "server": "mcp-auth-template",
      "timestamp": "2026-03-18T05:06:22.258Z"
    }
  },
  "jsonrpc": "2.0",
  "id": 3
}

Codex에 연결하기

이 프로젝트를 Codex에 붙일 때는 HTTP가 아니라 stdio를 사용합니다.

이유:

• Codex가 MCP 서버를 자식 프로세스로 직접 실행할 수 있음
• 포트를 따로 열 필요가 없음
• 로컬 실습이 더 단순함

Codex 설정

~/.codex/config.toml에 아래를 추가합니다.

[mcp_servers.hello_local]
command = "node"
args = ["/Users/leeseungchan/develop/mcp/src/stdio.js"]

이 프로젝트에서 Codex를 바로 쓰려면 trusted project 설정도 있으면 편합니다.

[projects."/Users/leeseungchan/develop/mcp"]
trust_level = "trusted"

Codex 실행

cd /Users/leeseungchan/develop/mcp
codex

Codex 안에서 테스트

Codex에 아래처럼 물어보면 됩니다.

사용 가능한 MCP 도구 보여줘

hello_local의 hello 툴 호출해줘

hello_local의 hello 툴을 name=MCP 로 호출해줘

stdio 방식에서 중요한 점

• npm run start:stdio를 미리 켜둘 필요는 없음
• Codex가 필요할 때 node /Users/leeseungchan/develop/mcp/src/stdio.js를 직접 실행
• Codex 세션이 끝나면 같이 종료되는 쪽으로 이해하면 됨

Claude 연결 튜토리얼

이 프로젝트를 Claude 쪽에 붙일 때도 stdio 방식을 쓰는 편이 가장 단순합니다.

방법 1. Claude Code CLI에서 바로 추가

Anthropic 공식 문서 기준으로 Claude Code는 로컬 stdio MCP 서버를 아래 형태로 추가할 수 있습니다.

claude mcp add hello-local -- node /Users/leeseungchan/develop/mcp/src/stdio.js

추가 후 확인:

claude mcp list

세부 설정 보기:

claude mcp get hello-local

이후 Claude Code를 실행한 뒤 다음처럼 요청하면 됩니다.

사용 가능한 MCP 도구 보여줘

hello-local의 hello 툴 호출해줘

방법 2. Claude Desktop 설정 파일에 직접 추가

Anthropic 공식 문서에는 Claude Desktop에서 claude_desktop_config.json의 mcpServers 항목으로 MCP 서버를 등록하는 예시가 나옵니다. 이 프로젝트를 붙일 때는 아래처럼 넣으면 됩니다.

{
  "mcpServers": {
    "hello-local": {
      "command": "node",
      "args": ["/Users/leeseungchan/develop/mcp/src/stdio.js"],
      "env": {}
    }
  }
}

Claude Desktop을 다시 열고 아래처럼 물어보면 됩니다.

사용 가능한 MCP 도구 보여줘

hello-local의 hello 툴을 name=Claude 로 호출해줘

참고

• Claude 쪽 연결도 HTTP가 아니라 stdio 사용을 권장
• 즉, npm run start:stdio를 미리 켜둘 필요 없음
• Claude가 필요할 때 node /Users/leeseungchan/develop/mcp/src/stdio.js를 직접 실행
• 팀 공유가 필요하면 Claude Code 문서의 --scope 또는 .mcp.json 방식을 쓰는 편이 좋음

지금 프로젝트에서 확인된 흐름

직접 확인한 동작은 아래입니다.

• HTTP 서버 기동
• GET /healthz 정상 응답
• 인증 없는 /mcp 요청에 401
• 인증된 initialize
• tools/list
• tools/call
• stdio 서버에서 initialize -> notifications/initialized -> tools/list -> tools/call
• Codex용 ~/.codex/config.toml에 hello_local 등록

다음 확장 포인트

이 템플릿은 여기서 확장하면 됩니다.

• hello 말고 툴 추가
• 툴 파일 분리
• Bearer 토큰 비교를 JWT 검증으로 교체
• 최종적으로 OAuth 기반 인증으로 확장
• resources / prompts 추가

참고

• HTTP 인증 로직: src/server.js
• 공통 MCP 툴 등록: src/mcp-server.js
• Codex 연결용 stdio 엔트리: src/stdio.js