MCP 연결

MCP 연결 (MCP connections)

MCP 서버는 도구 정의를 게시하고 도구 호출을 실행해요. Agents API가 도구를 발견하고, 서버를 호출하며, 결과를 에이전트에 돌려줘요. 애플리케이션이 각 호출을 직접 처리할 필요는 없어요.

출처: 문서

본문

서버가 도달 가능한 위치에 따라 연결이 실행되는 곳을 선택하세요:

연결	실행되는 곳	환경 필요 여부
`connection_origin: "service"` (기본값)인 HTTP	OpenAI	아니요
`connection_origin: "environment"`인 HTTP	사용자 세션의 환경	예
stdio	사용자 세션 환경의 프로세스	예

OpenAI에서 연결하기 (Connect from OpenAI)

agent.tools에 HTTP MCP 서버를 추가하세요. 서버는 OpenAI에서 도달 가능해야 해요. 세션 환경이 있든 없든 동작해요.

예를 들어 OpenAI 문서 MCP는 익명 접근을 허용해요:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

환경에서 연결하기 (Connect from your environment)

실행기 MCP는 세션의 환경에서 연결돼요. 사설 네트워크의 서버나 그 환경에 설치된 소프트웨어에 사용하세요.

세션의 environment.type을 self_hosted 또는 openai_hosted로 설정하세요. 자체 호스팅 환경이라면 에이전트가 도구를 사용하기 전에 실행기를 연결하세요.

HTTP로 연결하기 (Connect over HTTP)

이미 실행 중인 서버에는 HTTP를 사용하세요. agent.tools에 이 항목을 추가하고 URL을 환경이 도달할 수 있는 주소로 바꾸세요:

{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

여기서 localhost URL은 세션의 환경을 가리켜요. connection_origin을 생략하면 OpenAI가 대신 연결해요.

stdio로 서버 시작하기 (Start a server over stdio)

stdio를 사용하면 실행기가 서버 프로세스를 시작해요. 먼저 환경에 서버와 그 의존성을 설치하세요.

이 고객 조회 예시에서는 MCP SDK를 설치하세요:

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

서버를 /workspace/lookup_mcp.py로 저장하세요:

고객 조회 MCP 서버 실행하기

import sys

from mcp.server.fastmcp import FastMCP

server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)


@server.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer in the example data."""
    customers = {"123": {"name": "Example Customer", "plan": "pro"}}
    return {"customer": customers.get(customer_id)}


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
    server.run(transport=transport)

서버를 agent.tools에 추가하세요. stdio 인자는 스크립트의 트랜스포트를 선택해요:

{
  "type": "mcp",
  "server_label": "customer_lookup",
  "transport": {
    "type": "stdio",
    "command": "/workspace/mcp-demo/bin/python",
    "args": ["/workspace/lookup_mcp.py", "stdio"],
    "cwd": "/workspace"
  },
  "required": true
}

stdio에서는 command와 절대 경로 cwd가 필수이고 args는 선택이에요. connection_origin은 생략하세요.

고객 123을 조회하라고 에이전트에 메시지를 보내세요. 도구가 pro 플랜의 Example Customer를 반환해요.

OpenAI 호스팅 stdio MCP에서는 네트워크 정책을 생략하거나 enabled로 설정하세요. 이 연결에는 disabled와 restricted 네트워크 정책이 지원되지 않아요.

인증 추가하기 (Add authentication)

익명 접근을 허용하는 서버라면 인증 필드와 vault_ids를 생략하세요. 그 외에는 연결에 사용할 자격 증명 소스를 선택하세요:

한 세션용 HTTP 자격 증명: 세션을 만들 때 transport.authorization 또는 transport.headers를 설정하세요. Agents API는 이 값을 암호화하고 반환되는 세션 리소스에서 생략해요.
재사용 가능한 HTTP 자격 증명: 볼트에 MCP 자격 증명을 저장하고 vault_ids로 연결하세요. 볼트 기반 MCP 인증은 OpenAI에서의 연결에만 적용돼요. 자격 증명은 서버 URL과 일치하며, 여러 개가 일치할 때 credential_id로 하나를 선택해요.
Stdio 자격 증명: 환경에서 값을 제공하고 그 이름을 transport.env_vars에 나열하세요. 이 값은 환경에서 실행되는 코드가 읽을 수 있어요. 자체 호스팅 세션은 transport.env의 인라인 값을 받아들이지 않아요.

예를 들어 HTTP 트랜스포트는 베어러 토큰과 다른 헤더를 포함할 수 있어요:

{
  "type": "http",
  "server_url": "https://mcp.example.com/mcp",
  "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
  "headers": { "X-Tenant-ID": "tenant_123" }
}

Authorization에는 인라인 구성 또는 일치하는 볼트 자격 증명 중 한 소스만 사용하세요. 다른 헤더는 볼트 인증과 함께 쓸 수 있어요. 환경 출발 HTTP는 볼트 자격 증명을 사용하지 않아요. 인라인 인증이나 신뢰할 수 있는 프록시를 사용하세요.

시크릿을 재사용 가능한 에이전트 정의, 플러그인 아카이브, 로그에 넣지 마세요. 자격 증명을 에이전트가 생성한 코드가 접근할 수 없게 하려면 환경 밖에서 제공하는 신뢰할 수 있는 프록시나 서버를 사용하세요.

도구 접근과 시작 제어하기 (Control tool access and startup)

allowed_tools를 설정해 에이전트가 발견하고 호출할 수 있는 도구를 제한하세요. required: true를 설정하면 서버가 초기화하지 못할 때 턴을 실패시켜요. 초기화는 기본적으로 선택적이에요.

모든 MCP 구성 필드는 Create session 레퍼런스를 참고하세요.

연결 문제 해결하기 (Troubleshoot connections)

필수 서버가 초기화하지 못하면 agent.session.turn.failed의 오류를 검사하세요. stdio 서버라면 MCP 프로세스 로그도 확인하세요.

네트워크 접근: URL과 connection_origin을 확인하세요. 환경 연결이라면 실행기가 연결됐는지, 그 네트워크가 서버에 도달할 수 있는지 확인하세요.
자격 증명: 토큰이나 헤더를 확인하세요. 볼트라면 자격 증명이 서버 URL과 일치하는지 확인하세요.
실행 파일과 의존성: 구성한 명령이 환경 안에서 실행되는지 확인하세요.
작업 디렉터리: 인라인 stdio 구성에는 존재하는 절대 cwd를 사용하세요.

플러그인은 MCP 구성과 스킬을 패키징해 세션 간에 재사용할 수 있게 해 줘요.
Tool search는 지원되는 모델과 프로바이더에서 자동 MCP 도구 발견을 설명해요.

더 알아보기 (Learn more)

함수 도구 가이드에서 애플리케이션 코드를 호출하는 방법을 확인하세요.
Vaults 가이드에서 MCP 자격 증명을 안전하게 저장하는 방법을 확인하세요.