원격 MCP 서버, 붙이기 전에 볼 세 가지

이번 주 정리는 원격 MCP 서버다. 결론은 짧다. 앞의 둘은 사양이 정해 두었고, 셋째는 사양이 정해 주지 않는다. 그래서 셋째가 가장 자주 사고를 낸다.

01 원격 서버는 무엇으로 말하나?

원격 서버는 Streamable HTTP 로 말한다. 요청은 HTTP POST 한 번이고, 응답이 길면 같은 연결에서 스트림으로 이어 보낸다. 예전의 "HTTP 와 SSE 두 엔드포인트" 방식은 사양 개정판에서 이것으로 바뀌었다.

02 인증은 누가 하나?

원격 서버는 OAuth 로 보호된 자원이다. 클라이언트는 서버가 내놓는 메타데이터에서 인가 서버를 찾아 토큰을 받는다. 토큰은 그 서버 전용이어야 한다.

{
  "resource": "https://mcp.example.com",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["tools:read", "tools:call"]
}

03 같은 도구를 두 번 부르면?

사양은 도구 호출이 한 번만 실행된다고 보장하지 않는다. 응답이 늦어 클라이언트가 다시 보내면, 서버는 같은 일을 두 번 한다. 읽기 도구면 괜찮지만 비용이 드는 도구면 곤란하다.

우리 환경에서 확인한 것

이미지 생성 도구를 명령줄 래퍼로 여러 장 부르다가, 응답을 기다리던 래퍼가 같은 요청을 한 번 더 보냈다. 네 장을 부탁했는데 여덟 장 값이 나갔다. 지금은 배치 도구 하나로 네 장을 한 번에 요청하고, 결과는 작업 ID 로 기다린다.

// 재시도해도 한 번만 실행되게 — 도구가 받아 주면 호출마다 멱등 키를 붙인다
const key = crypto.randomUUID();
await client.callTool({
  name: "generate_batch",
  arguments: { prompts, idempotencyKey: key },
});

04 이번 주에 확인할 것

• 완료: 붙인 원격 서버가 Streamable HTTP 인지 본다
• 완료: 토큰이 서버마다 따로인지 본다
• 할 일: 비용이 드는 도구의 재시도 설정을 점검한다