MCP 서버

MCP 서버 (MCP servers)

함수 호출로 모델에 제공하는 도구에 더해, 원격 MCP 서버나 Secure MCP Tunnel로 모델에 새 기능을 줄 수 있어요. 이 도구들은 모델이 사용자 프롬프트에 응답할 때 필요하면 외부 서비스에 연결·제어할 수 있게 해줘요. 도구 호출은 자동으로 허용되거나, 개발자인 여러분의 명시적 승인이 필요하도록 제한될 수 있어요.

• 원격 MCP 서버는 공개 인터넷에서 원격 Model Context Protocol(MCP) 서버를 구현하는 모든 서버일 수 있어요.
• Secure MCP Tunnel은 공개 인터넷에 노출하지 않고 로컬·사설 MCP 서버를 연결해요.

출처: 문서

본문

이 가이드는 Responses API에서 MCP 도구를 쓰는 방법을 보여줘요. 내장 커넥터는 기존 모델에 계속 지원되고, 레거시 커넥터에서 폐기 정책과 호환성 예시를 볼 수 있어요. Agents API 세션에서는 MCP 연결을 참고하세요.

Secure MCP Tunnel

MCP 서버가 사설·온프레미스·방화벽 뒤에 있다면, 서버를 공개 인터넷에 노출하지 않고 지원 OpenAI 제품에 연결하려고 Secure MCP Tunnel을 쓰세요. openai/tunnel-client에서 최신 공개 릴리스를 다운로드하세요.

Quickstart

Responses API에서 mcp 도구 유형을 쓰세요. 원격 MCP 서버에는 server_url을, Secure MCP Tunnel을 통한 로컬 MCP 서버에는 tunnel_id를 설정하세요. 서버에 따라 authorization 파라미터에 OAuth 액세스 토큰이 필요할 수도 있어요.

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://dmcp-server.deno.dev/mcp",
            "require_approval": "never",
        },
    ],
    input="Roll 2d4+1",
)

print(resp.output_text)

개발자는 Responses API와 함께 쓰는 원격 MCP 서버를 믿는 것이 매우 중요해요. 악성 서버가 모델 컨텍스트에 들어오는 어떤 것이든 민감 데이터를 유출할 수 있어요. 이 도구를 쓰기 전에 아래 Risks and Safety 섹션을 주의 깊게 검토하세요.

API는 모델 응답의 output 배열에 새 항목을 반환해요. 모델이 MCP 서버를 쓰기로 하면 먼저 서버에서 사용 가능한 도구 목록을 요청하고, 그게 mcp_list_tools 출력 항목을 만들어요.

{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "dmcp",
  "tools": [
    {
      "annotations": null,
      "description": "Given a string of text describing a dice roll...",
      "input_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "diceRollExpression": {
            "type": "string"
          }
        },
        "required": ["diceRollExpression"],
        "additionalProperties": false
      },
      "name": "roll"
    }
  ]
}

모델이 MCP 서버의 사용 가능한 도구 중 하나를 호출하기로 하면, mcp_call 출력도 찾을 수 있어요. 이것은 모델이 MCP 도구에 보낸 것과 MCP 도구가 출력으로 돌려보낸 것을 보여줘요.

{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"diceRollExpression\":\"2d4 + 1\"}",
  "error": null,
  "name": "roll",
  "output": "4",
  "server_label": "dmcp"
}

동작 방식

MCP 도구는 대부분의 최신 모델의 Responses API에서 사용할 수 있어요. 모델별 MCP 도구 호환성은 여기에서 확인하세요. MCP 도구를 쓸 때는 도구 정의를 가져오거나 도구 호출을 할 때 사용된 토큰에만 비용을 내요. 도구 호출당 추가 요금은 없어요.

1단계: 사용 가능한 도구 나열하기

tools 파라미터에 원격 MCP 서버를 지정하면 API가 서버에서 도구 목록을 가져오려 시도해요. Responses API는 Streamable HTTP 또는 HTTP/SSE 전송 프로토콜을 지원하는 원격 MCP 서버와 함께 작동해요. 도구 목록 검색에 성공하면 모델 응답 output에 새 mcp_list_tools 출력 항목이 나타나고, 이 객체의 tools 속성은 성공적으로 가져온 도구를 보여줘요.

API 요청 컨텍스트에 mcp_list_tools 항목이 있는 동안, 대화의 각 턴에서 API가 MCP 서버에서 도구 목록을 다시 가져오지 않아요. 지연을 최적화하려면 이 항목을 매 대화·워크플로 실행의 모델 컨텍스트 일부로 유지하는 것을 권장해요.

도구 필터링 — 일부 MCP 서버는 수십 개 도구를 가질 수 있고, 모델에 많은 도구를 노출하면 높은 비용·지연이 발생할 수 있어요. MCP 서버가 노출하는 도구의 일부만 관심 있다면 allowed_tools 파라미터로 그 도구만 가져올 수 있어요.

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://dmcp-server.deno.dev/mcp",
            "require_approval": "never",
            "allowed_tools": ["roll"],
        }
    ],
    input="Roll 2d4+1",
)

2단계: 도구 호출하기

모델이 MCP 서버의 사용 가능한 도구를 호출하기로 하면 API가 MCP 서버로 도구 호출을 보내고, 서버가 반환한 결과를 모델 컨텍스트에 추가해 모델이 최종 응답을 만들게 해요. 이 과정은 mcp_call 출력으로 표시되고, require_approval 설정에 따라 승인 흐름이 필요할 수 있어요.

인증 (Authentication)

대부분의 MCP 서버는 인증이 필요해요. 가장 일반적인 방식은 OAuth 액세스 토큰이에요. MCP 도구의 authorization 필드로 이 토큰을 제공해요.

import os
from openai import OpenAI

client = OpenAI()
authorization = os.environ["STRIPE_OAUTH_ACCESS_TOKEN"]

resp = client.responses.create(
    model="gpt-6-astra",
    input="Create a payment link for $20",
    tools=[
        {
            "type": "mcp",
            "server_label": "stripe",
            "server_url": "https://mcp.stripe.com",
            "authorization": authorization,
        }
    ],
)

print(resp.output_text)

MCP 서버에서 도구 로딩 연기하기

tool search를 쓰면, MCP 서버가 노출하는 함수를 모델이 필요하다고 판단할 때까지 로딩을 연기할 수 있어요. MCP 서버 도구 정의에 defer_loading: true를 설정하세요. 연기하면 모델이 MCP 서버의 라벨·설명으로 언제 검색할지 결정할 수 있지만, 개별 함수 정의는 필요할 때만 로드돼요. 전체 토큰 사용을 줄이는 데 도움이 되고, 많은 함수를 노출하는 MCP 서버에 가장 유용해요.

{
    "type": "mcp",
    "server_label": "dmcp",
    "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
    "server_url": "https://dmcp-server.deno.dev/mcp",
    "defer_loading": true,
    "require_approval": "never"
}

위험과 안전 (Risks and safety)

MCP 도구는 OpenAI 모델을 외부 서비스에 연결하게 해줘요. 강력한 기능이지만 몇 가지 위험이 있어요. 커넥터는 민감 데이터를 OpenAI에 보내거나, 모델이 그 서비스의 잠재적 민감 데이터에 읽기 접근하게 할 위험이 있어요. 원격 MCP 서버도 같은 위험을 지니지만 OpenAI가 검증하지 않았어요. 이 서버들은 모델이 데이터에 접근·송수신하고 서비스에서 조치를 취하게 할 수 있어요. 모든 MCP 서버는 자체 이용 약관이 적용되는 서드파티 서비스예요. 악성 MCP 서버를 발견하면 [email protected]에 신고하세요.

통합할 때 고려할 모범 사례:

• 프롬프트 주입(Prompt injection): 프롬프트 주입은 모든 LLM 앱의 중요한 보안 고려사항이고, 민감 데이터에 접근하거나 조치를 취할 수 있는 MCP 서버·커넥터에 모델 접근을 줄 때 특히 그래요. 모델 프롬프트에 사용자 제공 콘텐츠가 있으면 이 도구를 적절한 주의·보호 조치와 함께 쓰세요.
• 민감 액션에는 항상 승인 요구: require_approval과 allowed_tools 파라미터의 사용 가능한 구성을 이용해 민감 액션이 항상 승인 흐름을 거치게 하세요.
• MCP 도구 호출·출력의 URL: 커넥터나 원격 MCP 서버의 도구 호출 출력으로 제공된 URL을 요청하거나 이미지 URL을 임베드하는 것은 위험할 수 있어요. 앱 코드에서 임베드·사용하기 전에 그 URL을 제공하는 도메인·서비스가 신뢰할 수 있는지 확인하세요.
• 신뢰하는 서버에 연결: 서비스 제공자가 직접 호스팅하는 공식 서버를 고르세요(예: 서드파티가 호스팅하는 Stripe MCP 서버 대신 Stripe가 mcp.stripe.com에 호스팅하는 서버에 연결 권장). 요즘 공식 원격 MCP 서버가 많지 않아서, 그 서비스를 운영하지 않는 조직이 호스팅하고 여러분의 API를 통해 그 서비스로 요청을 프록시하는 MCP 서버를 쓰고 싶을 수 있어요. 그런 경우 이 "애그리게이터"에 대한 실사를 특별히 조심하고 데이터 이용 방식을 주의 깊게 검토하세요.
• 서드파티 MCP 서버와 공유하는 데이터 로그·검토: MCP 서버는 자체 도구 정의를 정의하므로, 호스트와 공유하기 불편할 수 있는 데이터를 요청할 수 있어요. 그래서 Responses API의 MCP 도구는 기본적으로 각 MCP 도구 호출의 승인을 요구해요. 앱을 개발할 때 이 MCP 서버와 공유하는 데이터 유형을 주의 깊고 견고하게 검토하세요. 신뢰가 생기면 승인을 건너뛰어 실행 지연을 줄일 수 있어요.
• MCP 서버에 보내는 모든 데이터를 기록하는 것도 권장해요. store=true로 Responses API를 쓰면 이 데이터는 조직에 Zero Data Retention이 활성화되지 않는 한 API가 30일간 기록해요. 자체 시스템에도 기록해 주기적으로 검토해 데이터가 기대대로 공유되는지 확인하세요.
• 악성 MCP 서버는 OpenAI 모델이 예상치 못하게 행동하게 하는 숨은 지시(프롬프트 주입)를 포함할 수 있어요. OpenAI는 이 위협을 감지·차단하는 내장 안전장치를 구현했지만, 입력·출력을 주의 깊게 검토하고 신뢰하는 서버와만 연결을 설정하는 것이 필수적이에요. MCP 서버는 예기치 않게 도구 동작을 수정해 의도하지 않거나 악성인 동작으로 이어질 수 있어요.

Zero Data Retention·Data Residency에 미치는 영향 — MCP 도구는 Zero Data Retention과 Data Residency와 호환되지만, MCP 서버는 서드파티 서비스이고 MCP 서버에 보낸 데이터는 그들의 데이터 보존·거주 정책이 적용돼요. 유럽에 Data Residency가 있는 조직이면, OpenAI는 MCP 서버로 통신·데이터가 보내지는 시점까지는 고객 콘텐츠의 추론·저장을 유럽에서만 하도록 제한해요. MCP 서버도 여러분이 가진 Zero Data Retention·Data Residency 요구사항을 준수하는지 확인하는 건 여러분의 책임이에요. 자세한 내용은 여기에서 배울 수 있어요.

사용 메모

MCP 도구는 Responses, Chat Completions, Assistants API에서 사용할 수 있고, rate limit은 Tier 1에서 200 RPM, Tier 2·3에서 1000 RPM, Tier 4·5에서 2000 RPM이에요. 자세한 내용은 Pricing과 ZDR and data residency를 참고하세요.

더 알아보기 (Learn more)

• Secure MCP Tunnel
• 도구 사용하기
• Tool search
• Agents API MCP 연결