MCP 서버 개발 체크리스트

# 1. app + sp 동시 생성
az ad app create --display-name "Blueprint MCP" --sign-in-audience AzureADMyOrg
az ad sp create --id APP_ID   # ← 명시적 SP 생성, 자동 생성 안 됨
 
# 2. identifierUris (= App ID URI)
az ad app update --id APP_ID --identifier-uris "https://axe.axelabs.ai/blueprint/mcp"
 
# 3. accessTokenAcceptedVersion = 2 (v2 endpoint 가 표준)
az rest --method PATCH --uri "https://graph.microsoft.com/v1.0/applications/OBJECT_ID" \
  --body '{"api":{"requestedAccessTokenVersion":2}}'
 
# 4. oauth2PermissionScopes (delegated permission)
az rest --method PATCH ... --body '{
  "api": {"oauth2PermissionScopes":[{
    "id":"RANDOM_UUID",
    "value":"mcp.access",
    "type":"User",
    "isEnabled":true,
    "adminConsentDisplayName":"Access Blueprint MCP",
    "userConsentDisplayName":"Access Blueprint MCP"
  }]}
}'
 
# 5. redirectUris (claude.ai 의 양쪽 도메인)
az rest --method PATCH ... --body '{"web":{"redirectUris":[
  "https://claude.ai/api/mcp/auth_callback",
  "https://claude.com/api/mcp/auth_callback"
]}}'
 
# 6. requiredResourceAccess (Microsoft Graph User.Read — id_token 의 email claim 발급)
az rest --method PATCH ... --body '{"requiredResourceAccess":[{
  "resourceAppId":"00000003-0000-0000-c000-000000000000",
  "resourceAccess":[{"id":"e1fe6dd8-ba31-4d61-89e7-88639da4683d","type":"Scope"}]
}]}'
 
# 7. implicitGrantSettings.enableIdTokenIssuance = true
az rest --method PATCH ... --body '{"web":{"implicitGrantSettings":{"enableIdTokenIssuance":true}}}'
 
# 8. client_secret 생성 + vault push (stderr 분리 필수)
az ad app credential reset --id APP_ID --years 2 --query password -o tsv 2>/dev/null \
  | axe secret push CUSTOMER/SERVICE/mcp-client-secret -
 
# 9. tenant admin consent (필요 시 Azure Portal 에서 1 클릭)
#    User.Read + mcp.access 둘 다 grant

az ad app show --id APP_ID --query "{accessTokenAcceptedVersion:api.requestedAccessTokenVersion, identifierUris:identifierUris, signInAudience:signInAudience}" -o json

- hostname: axe.axelabs.ai
  path: ^/SERVICE/mcp(/.*)?$
  service: http://host.docker.internal:PROXY_PORT
 
- hostname: axe.axelabs.ai
  path: ^/SERVICE/\.well-known/oauth-protected-resource(/.*)?$
  service: http://host.docker.internal:PROXY_PORT

:80 {
    reverse_proxy SERVICE-mcp:3000 {
        lb_try_duration 5s
        lb_try_interval 250ms
        header_up Host {http.request.host}
    }
    encode gzip
    log { output stdout; format console; level INFO }
}

# ① httpx.Timeout — 4-arg 또는 default 명시. partial kwargs 는 0.28 부터 ValueError.
_JWKS_HTTP_TIMEOUT = httpx.Timeout(connect=2.0, read=3.0, write=2.0, pool=5.0)
#                                                          ^^^^^^^^^^^^^^^^^^^^ 빠뜨리면 500
 
# ② audience = [client_id GUID, application_id_uri]
#    v2 endpoint 의 access_token aud = client_id GUID (NOT App ID URI).
#    PyJWT 가 list 의 any 매칭. 둘 다 줘야 v1/v2 양립.
expected_audiences: list[str] = [get_client_id(), get_app_id_uri()]
payload = pyjwt.decode(
    token, public_key,
    algorithms=["RS256"],
    audience=expected_audiences,       # ← list, 단일 string 금지
    issuer=[get_microsoft_issuer(), get_microsoft_issuer_v1()],
    options={"require": ["exp","iat","iss","aud","sub"]},
    leeway=60,
)
 
# ③ JWKS cache + fail cooldown + kid-miss force refetch
#    Microsoft 의 key rotation 대응. frame/auth_oidc.py:47-78 그대로.
 
# ④ email claim fallback 순서
email = (payload.get("email")
         or payload.get("preferred_username")
         or payload.get("upn") or "").strip().lower()

# ① lifespan forward — Starlette Mount 는 child lifespan 미전파
def build_app() -> Starlette:
    mcp_app = mcp.streamable_http_app()
    @asynccontextmanager
    async def _lifespan(app: Starlette):
        async with mcp_app.router.lifespan_context(app):  # ← 안 부르면
            try:
                yield                                       #   "Task group not initialized"
            finally:
                await db_shutdown()
 
# ② 401 reason 노출 (body + log)
def _unauthorized(request, request_id, reason):
    log.warning("401 %s reason=%s", request.url.path, reason)
    body = {"error": {
        "code": _map_code(reason),    # MISSING_TOKEN / INVALID_TOKEN / USER_NOT_PROVISIONED / UNAUTHORIZED
        "message": reason,             # ← 고정 string 금지. reason 그대로.
        "context": {"request_id": request_id, "reason": reason},
        ...
    }}
    # WWW-Authenticate resource_metadata = APP_ID_URI 에서 /mcp suffix strip + /.well-known/...
 
# ③ FastMCP DNS-rebinding guard 우회 — main() 안에서 build_app() 전에:
allowed_hosts = os.environ.get("SERVICE_MCP_ALLOWED_HOSTS")
if allowed_hosts:
    mcp.settings.transport_security.allowed_hosts = [h.strip() for h in allowed_hosts.split(",") if h.strip()]
# 안 하면 axe.axelabs.ai 가 421 Misdirected Request
 
# ④ Route mount: cloudflared 가 path 그대로 보내므로 `/SERVICE/` mount + 화이트리스트
routes = [
    Route("/health", health),
    Route("/SERVICE/health", health),
    Route("/SERVICE/.well-known/oauth-protected-resource", oauth_protected_resource),
    Mount("/SERVICE", app=mcp_app),
]
 
# ⑤ JWTAuthMiddleware 의 public-path 화이트리스트도 `/SERVICE/` prefix 포함
if path in ("/health", "/SERVICE/health", "/SERVICE/.well-known/oauth-protected-resource", ...):
    return await call_next(request)

mcp:
  build: { context: .., dockerfile: mcp/Dockerfile }
  container_name: SERVICE-mcp
  env_file: ../.env
  environment:
    - SERVICE_MCP_PORT=3000
    - SERVICE_MCP_APP_ID_URI=${SERVICE_MCP_APP_ID_URI:-https://axe.axelabs.ai/SERVICE/mcp}
    - AZURE_AD_TENANT_ID=${AZURE_AD_TENANT_ID:-122fb574-...}
    # ① allowed_hosts (axe.axelabs.ai + 컨테이너 DNS + localhost)
    - SERVICE_MCP_ALLOWED_HOSTS=SERVICE-mcp:*,localhost:*,127.0.0.1:*,host.docker.internal:*,axe.axelabs.ai
    - SERVICE_MCP_ALLOWED_ORIGINS=https://axe.axelabs.ai,https://claude.ai,https://claude.com
  networks:
    default:
      aliases:
        - SERVICE-mcp
    # ② artemis network 도 참여 (axelabs-tunnel 같은 네트워크여야 cloudflared 가 닿음)
    artemis:
  # ③ Python 이미지면 curl healthcheck (Node 잔재 `node -e fetch(...)` 금지)
  healthcheck:
    test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/health"]
    interval: 30s
    timeout: 5s
    retries: 3
    start_period: 10s
  depends_on:
    postgres:
      condition: service_healthy

azure_apps:
  CUSTOMER:
    SERVICE_mcp:                # D-SERVICE-mcp-1
      client_id: "GUID"
      application_id_uri: "https://axe.axelabs.ai/SERVICE/mcp"
      scopes:
        - "https://axe.axelabs.ai/SERVICE/mcp/mcp.access"
      # client_secret 는 vault 에서 pull (env 명시)
      client_secret_env: "AZURE_SERVICE_MCP_CLIENT_SECRET"
 
services:
  SERVICE:
    env_file: "/Users/axe/SERVICE/.env"
    secrets:
      - { env: AZURE_SERVICE_MCP_CLIENT_SECRET, vault: "SERVICE/CUSTOMER/mcp-client-secret", rotation_external: azure }
      # 기타 비밀들 ...

docker logs SERVICE-mcp --since 5m 2>&1 | grep -iE "401|reason|warning|error|exception|task group|invalid" | head -30

docker logs axe-SERVICE-mcp-proxy --since 5m 2>&1 | grep -E '"status": [45]' | tail -20

curl -X POST https://axe.axelabs.ai/SERVICE/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXN0IjoxfQ.invalid" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | jq .error