How do I use MCP Auth Template?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Auth Template call the hello tool with name World" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 같은 로컬 클라이언트용

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

빠른 시작

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

MCP Auth Template

MCP Auth Template

구성

빠른 시작

1. 설치

2. 환경 변수 준비

실행 방식

HTTP 서버 실행

stdio 서버 실행

Transport 차이

HTTP

stdio

HTTP 인증

HTTP MCP 실습 예제

1. Health check

2. initialize

3. initialized notification

4. tools/list

5. hello tool 호출

Codex에 연결하기

Codex 설정

Codex 실행

Codex 안에서 테스트

stdio 방식에서 중요한 점

Claude 연결 튜토리얼

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

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

참고

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

다음 확장 포인트

참고

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API