팀 전체가 안전하게 공유하는 엔터프라이즈 Model Context Protocol 서버 구축 가이드: Streamable HTTP와 OAuth 2.1 실전 구현

1. 클라이언트 → MCP 서버: 토큰 없이 요청
2. MCP 서버 → 클라이언트: 401 Unauthorized
                          + WWW-Authenticate 헤더 (메타데이터 위치 안내)
3. 클라이언트 → IdP: PKCE 포함 Authorization Code Flow 시작
4. IdP → 클라이언트: 인가 코드 발급
5. 클라이언트 → IdP: 코드 + PKCE verifier로 액세스 토큰 요청
6. IdP → 클라이언트: 단기 액세스 토큰(JWT) 발급
7. 클라이언트 → MCP 서버: Bearer 토큰과 함께 재요청
8. MCP 서버: 토큰 검증
   ┌─ JWT 방식(권장): JWKS 공개 키로 서명을 로컬 검증 → IdP 추가 요청 없음
   └─ Introspection 방식: IdP의 /introspect 엔드포인트에 검증 요청
9. MCP 서버 → 클라이언트: 정상 응답

import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { randomUUID } from "crypto";
import { z } from "zod";
 
const app = express();
app.use(express.json());
 
// 세션별 transport 인스턴스 관리 (Stateful 모드)
// ⚠️ 주의: 이 Map은 단일 프로세스 메모리에 저장됩니다.
// 서버 재시작 시 모든 세션이 유실됩니다.
// 프로덕션에서는 반드시 Redis 등 외부 저장소로 교체가 필요합니다.
const sessions = new Map<string, StreamableHTTPServerTransport>();
 
function createMcpServer() {
  const server = new McpServer({
    name: "enterprise-mcp-server",
    version: "1.0.0",
  });
 
  server.tool(
    "get_jira_issue",
    "Jira 이슈 정보를 조회합니다",
    {
      issueKey: z.string().describe("Jira 이슈 키 (예: PROJ-123)"),
    },
    async ({ issueKey }) => {
      // 실제 구현에서는 Jira REST API 호출
      return {
        content: [{ type: "text", text: `이슈 ${issueKey}: [API 응답 데이터]` }],
      };
    }
  );
 
  return server;
}
 
// 단일 엔드포인트로 GET/POST/DELETE 모두 처리
app.all("/mcp", async (req, res) => {
  try {
    const sessionId = req.headers["mcp-session-id"] as string | undefined;
    let transport: StreamableHTTPServerTransport;
 
    if (sessionId && sessions.has(sessionId)) {
      transport = sessions.get(sessionId)!;
    } else if (!sessionId && req.method === "POST") {
      const newSessionId = randomUUID();
      transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: () => newSessionId,
        // 스트리밍이 불필요한 요청은 일반 JSON으로 응답해 리소스 절감
        enableJsonResponse: true,
      });
 
      const server = createMcpServer();
      await server.connect(transport);
      sessions.set(newSessionId, transport);
 
      // ⚠️ setTimeout은 프로세스 재시작 시 초기화됩니다.
      // 슬라이딩 윈도우 방식이 필요하면 Redis TTL을 활용하세요.
      setTimeout(() => sessions.delete(newSessionId), 30 * 60 * 1000);
    } else {
      res.status(400).json({ error: "Invalid session" });
      return;
    }
 
    await transport.handleRequest(req, res);
  } catch (err) {
    console.error("MCP 요청 처리 오류:", err);
    if (!res.headersSent) {
      res.status(500).json({ error: "Internal server error" });
    }
  }
});
 
app.listen(3000, () => {
  console.log("MCP 서버가 http://localhost:3000/mcp 에서 실행 중입니다");
});

[AI Client: Claude / Cursor]
         │
         ▼
[MCP Gateway / Proxy]  ← 토큰 검증, RBAC, 감사 로그, 속도 제한
         │
         ├── JWT 서명 검증 → [JWKS: Okta / Azure AD / Keycloak]
         │
         ▼
┌─────────────────────────────────┐
│  [MCP Server A: Jira Tools]     │
│  [MCP Server B: DB Query Tools] │
│  [MCP Server C: CI/CD Tools]    │
└─────────────────────────────────┘

import { Request, Response, NextFunction } from "express";
import { createRemoteJWKSet, jwtVerify } from "jose";
 
// IdP의 JWKS 엔드포인트 — JWT 서명 검증에 필요한 공개 키를 동적으로 가져옵니다.
// 키 교체(rotation) 시 별도 배포 없이 자동 대응됩니다.
const JWKS = createRemoteJWKSet(
  new URL("https://your-idp.example.com/.well-known/jwks.json")
);
 
// 도구별 필요 스코프 매핑 테이블
const TOOL_SCOPE_MAP: Record<string, string[]> = {
  get_jira_issue:    ["jira.read"],
  create_jira_issue: ["jira.write"],
  trigger_pipeline:  ["cicd.trigger"],  // 고위험 작업은 별도 스코프로 격리
  query_database:    ["db.read"],
};
 
export async function authMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
) {
  const authHeader = req.headers.authorization;
 
  if (!authHeader?.startsWith("Bearer ")) {
    // RFC 9728: 인증 실패 시 메타데이터 위치를 클라이언트에게 안내
    res.setHeader(
      "WWW-Authenticate",
      `Bearer realm="mcp", resource_metadata="https://mcp.yourcompany.com/.well-known/oauth-protected-resource"`
    );
    res.status(401).json({ error: "Authentication required" });
    return;
  }
 
  try {
    const token = authHeader.slice(7);
    // JWT 서명을 JWKS 공개 키로 로컬 검증 — IdP에 추가 요청 없음
    const { payload } = await jwtVerify(token, JWKS, {
      audience: "https://mcp.yourcompany.com",
    });
 
    // MCP JSON-RPC 요청에서 도구명 추출
    // tools/call 이외의 메서드(initialize, tools/list 등)는 null 반환
    const requestedTool = extractToolName(req.body);
 
    if (requestedTool !== null) {
      // tools/call 요청: 도구별 스코프 검증
      const requiredScopes = TOOL_SCOPE_MAP[requestedTool] ?? [];
      const tokenScopes = ((payload.scope as string) ?? "").split(" ");
      const hasPermission = requiredScopes.every((s) => tokenScopes.includes(s));
 
      if (!hasPermission) {
        await auditLog({
          userId: payload.sub,
          tool: requestedTool,
          result: "DENIED",
          requiredScopes,
          tokenScopes,
          timestamp: new Date(),
        });
        res.status(403).json({ error: "Insufficient scope", required: requiredScopes });
        return;
      }
    }
    // tools/call 이외의 요청(initialize 등)은 토큰 유효성만 확인 후 통과
 
    (req as any).user = payload;
    next();
  } catch (err) {
    res.status(401).json({ error: "Invalid or expired token" });
  }
}
 
function extractToolName(body: any): string | null {
  // tools/call 메서드에서만 도구명을 추출합니다.
  // initialize, tools/list, resources/list 등 다른 메서드는 null 반환 →
  // 호출자(authMiddleware)에서 null 여부를 확인해 스코프 검사를 건너뜁니다.
  if (body?.method === "tools/call") {
    return body?.params?.name ?? null;
  }
  return null;
}

// worker.ts
// ⚠️ 아래 코드는 구조를 설명하는 의사 코드입니다.
// Cloudflare Agents SDK와 Vectorize API 시그니처는 변경될 수 있으므로
// 실제 구현 전 Cloudflare 공식 문서를 반드시 확인하세요.
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
 
export class MyMcpAgent extends McpAgent {
  server = new McpServer({ name: "cf-mcp-server", version: "1.0.0" });
 
  async init() {
    this.server.tool(
      "search_docs",
      "내부 문서를 검색합니다",
      { query: z.string() },
      async ({ query }) => {
        // Vectorize는 텍스트가 아닌 벡터 값을 직접 전달해야 합니다.
        // 실제 구현: AI Workers로 임베딩 생성 후 Vectorize에 질의합니다.
        const embedding = await this.env.AI.run(
          "@cf/baai/bge-small-en-v1.5",
          { text: query }
        );
        const results = await this.env.VECTORIZE_INDEX.query(
          embedding.data[0],
          { topK: 5 }
        );
        return {
          content: [{ type: "text", text: JSON.stringify(results) }],
        };
      }
    );
  }
}
 
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
 
    if (url.pathname === "/mcp") {
      // Cloudflare Zero Trust가 앞단에서 SSO 처리
      // 이미 인증된 요청만 이 핸들러에 도달합니다
      return MyMcpAgent.serve("/mcp").fetch(request, env);
    }
 
    return new Response("Not found", { status: 404 });
  },
};