Streamable HTTP와 OAuth 2.1로 MCP 서버 배포하기 — 멀티유저 환경부터 Azure AD 연동까지

클라이언트                         MCP 서버
   |                                  |
   |--- POST /mcp (initialize) ------>|
   |<-- 200 OK (JSON or SSE) ---------|
   |                                  |
   |--- POST /mcp (tools/call) ------>|
   |<-- 200 OK + SSE stream ----------|  ← 긴 작업의 경우
   |    data: {"progress": 50}        |
   |    data: {"result": "완료"}      |
   |                                  |
   |--- GET /mcp (listen) ----------->|  ← 서버 푸시 필요 시
   |<-- SSE stream (server-initiated)-|

MCP 클라이언트                인가 서버              MCP 서버
(Claude Desktop 등)         (Azure AD/Okta)        (내 서버)
      |                          |                      |
      |-- 1. /.well-known/oauth-protected-resource ----->|
      |<-- 2. 인가 서버 위치 반환 -----------------------|
      |                          |                      |
      |-- 3. PKCE 코드 요청 ---->|                      |
      |<-- 4. 인가 코드 반환 ----|                      |
      |-- 5. 토큰 교환 --------->|                      |
      |<-- 6. Access Token 발급--|                      |
      |                          |                      |
      |-- 7. POST /mcp (Bearer Token) ----------------->|
      |                          |    8. JWKS로 토큰 검증|
      |<-------------------------------- 9. 응답 --------|

import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
 
const TENANT_ID = process.env.AZURE_TENANT_ID!;
 
// 모듈 초기화 시 한 번만 JWKS 클라이언트 생성 (요청마다 생성하면 불필요한 오버헤드 발생)
const JWKS = createRemoteJWKSet(
  new URL(`https://login.microsoftonline.com/${TENANT_ID}/discovery/v2.0/keys`)
);
 
// express.Request를 확장한 타입으로 req.user 타입 안전성 확보
type AuthedRequest = express.Request & { user: JWTPayload };
 
const app = express();
app.use(express.json());
 
// OAuth 2.1 Protected Resource Metadata 엔드포인트
app.get("/.well-known/oauth-protected-resource", (req, res) => {
  res.json({
    resource: "https://mcp.example.com",
    authorization_servers: [
      `https://login.microsoftonline.com/${TENANT_ID}/v2.0`,
    ],
    bearer_methods_supported: ["header"],
  });
});
 
// Bearer 토큰 검증 미들웨어
async function verifyToken(
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith("Bearer ")) {
    res.status(401).json({ error: "unauthorized" });
    return;
  }
 
  const token = authHeader.slice(7);
  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: `https://login.microsoftonline.com/${TENANT_ID}/v2.0`,
      audience: "https://mcp.example.com", // RFC 8707: aud 클레임 검증
    });
    (req as AuthedRequest).user = payload;
    next();
  } catch (err) {
    res.status(401).json({ error: "invalid_token" });
  }
}
 
// 무상태 MCP 엔드포인트
app.all("/mcp", verifyToken, async (req, res) => {
  const server = new McpServer({ name: "enterprise-mcp", version: "1.0.0" });
 
  server.tool("get_user_info", "현재 사용자 정보 반환", {}, async () => {
    const user = (req as AuthedRequest).user;
    return {
      content: [
        { type: "text", text: `사용자: ${user.name} (${user.email})` },
      ],
    };
  });
 
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // 무상태: 세션 ID 없음
  });
 
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
 
app.listen(3000, () => console.log("MCP 서버 실행 중: http://localhost:3000"));

import asyncio
import os
import time
 
import httpx
from jose import jwt, JWTError
from mcp.server.fastmcp import FastMCP
 
TENANT_ID = os.environ["AZURE_TENANT_ID"]
 
# JWKS 캐싱 (1시간 TTL)
# 비동기 환경에서 동시 요청이 몰릴 경우 중복 갱신을 방지하기 위해
# asyncio.Lock으로 임계 구역을 보호하는 것을 권장합니다.
_jwks_cache: dict = {}
_jwks_lock = asyncio.Lock()
 
 
async def verify_token(token: str) -> dict:
    """Azure AD JWKS로 Bearer 토큰 검증"""
    cache_key = "azure_jwks"
 
    async with _jwks_lock:
        if cache_key not in _jwks_cache or time.time() > _jwks_cache[cache_key]["expires"]:
            async with httpx.AsyncClient() as client:
                resp = await client.get(
                    f"https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys"
                )
                _jwks_cache[cache_key] = {
                    "keys": resp.json(),
                    "expires": time.time() + 3600,  # 1시간 캐싱
                }
 
    try:
        payload = jwt.decode(
            token,
            _jwks_cache[cache_key]["keys"],
            algorithms=["RS256"],
            audience="https://mcp.example.com",  # RFC 8707 검증
            issuer=f"https://login.microsoftonline.com/{TENANT_ID}/v2.0",
        )
        return payload
    except JWTError as e:
        raise ValueError(f"토큰 검증 실패: {e}")
 
 
# FastMCP로 서버 정의
mcp = FastMCP("enterprise-mcp")
 
 
@mcp.tool()
async def search_documents(query: str) -> str:
    """기업 문서 검색 도구"""
    # 실제 구현에서는 검색 서비스 호출
    return f"'{query}'에 대한 검색 결과: 3건"
 
 
@mcp.tool()
async def get_employee_info(employee_id: str) -> str:
    """직원 정보 조회 (HR 시스템 연동)"""
    return f"직원 ID {employee_id}: 홍길동 / 개발팀"
 
 
# 무상태 Streamable HTTP 앱으로 변환
# stateless_http=True: 세션 상태 없음, json_response=True: 스트리밍 불필요 시 JSON 반환
app = mcp.streamable_http_app(stateless_http=True, json_response=True)
 
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

// azure-mcp-server/src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
 
// Managed Identity로 Key Vault 접근 (클라이언트 시크릿 불필요)
const credential = new DefaultAzureCredential();
const kvClient = new SecretClient(
  "https://my-keyvault.vault.azure.net",
  credential
);
 
export function createMcpServer() {
  const server = new McpServer({
    name: "azure-enterprise-mcp",
    version: "1.0.0",
  });
 
  server.tool(
    "get_secret",
    "Key Vault에서 시크릿 조회",
    { secretName: { type: "string", description: "시크릿 이름" } },
    async ({ secretName }) => {
      // ACA Easy Auth가 Bearer 토큰을 이미 검증했으므로
      // 여기서는 비즈니스 로직에만 집중할 수 있습니다
      const secret = await kvClient.getSecret(secretName);
      return {
        content: [{ type: "text", text: `값: ${secret.value}` }],
      };
    }
  );
 
  return server;
}

# Azure Container Apps 배포 설정
# Microsoft.App/containerApps 리소스 properties 블록 일부
properties:
  configuration:
    ingress:
      external: true
      targetPort: 3000
  template:
    containers:
      - name: mcp-server
        image: myregistry.azurecr.io/enterprise-mcp:latest
        env:
          - name: AZURE_CLIENT_ID
            value: "[managed-identity-client-id]"  # 시크릿 없이 Managed Identity 사용
          - name: AZURE_TENANT_ID
            secretRef: azure-tenant-id