MCP 서버는 도구 정의를 제공하고 도구 호출을 실행합니다. Agents API는 사용 가능한 도구를 검색하고 서버를 호출한 뒤 결과를 에이전트에 반환합니다. 애플리케이션에서 각 호출을 직접 처리할 필요는 없습니다.
어디에서 서버에 접근할 수 있는지에 따라 연결 위치를 선택하세요.
| 연결 방식 | 연결 위치 | 환경 필요 여부 |
|---|---|---|
HTTP(connection_origin: "service", 기본값) |
OpenAI | 아니요 |
HTTP(connection_origin: "environment") |
세션 환경 | 예 |
| stdio | 세션 환경에서 실행되는 프로세스 | 예 |
OpenAI에서 연결하기
HTTP MCP 서버를 agent.tools에 추가하세요. OpenAI에서 접근할 수 있는 서버여야 합니다. 세션 환경 유무와 관계없이 이 방식으로 연결할 수 있습니다.
예를 들어 OpenAI 문서 MCP 서버는 익명 접근을 허용합니다.
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp"
},
"connection_origin": "service",
"required": true
}
세션 환경에서 연결하기
실행기를 사용하는 MCP 연결은 세션 환경에서 시작됩니다. 사설 네트워크의 서버에 연결하거나 세션 환경에 설치된 소프트웨어를 사용할 때 이 방식을 선택하세요.
세션의 environment.type을 self_hosted 또는 openai_hosted로 설정하세요. 자체 호스팅 환경에서는 에이전트가 도구를 사용하기 전에 실행기를 연결하세요.
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
}이 구성에서 로컬호스트 URL은 세션 환경을 가리킵니다. connection_origin을 생략하면 OpenAI에서 연결합니다.
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에 저장하세요.
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을 조회해 달라는 메시지를 보내세요. 도구가 반환하는 고객 이름은 Example Customer이고 요금제는 pro입니다.
OpenAI가 호스팅하는 환경에서 stdio MCP를 사용할 때는 네트워크 정책을 생략하거나 enabled로 설정하세요. 이 연결 방식에서는 disabled 및 restricted 네트워크 정책을 지원하지 않습니다.
인증 추가하기
익명 접근을 허용하는 서버라면 인증 필드와 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 전송 설정에는 Bearer 토큰과 추가 헤더를 함께 지정할 수 있습니다.
{
"type": "http",
"server_url": "https://mcp.example.com/mcp",
"authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
"headers": { "X-Tenant-ID": "tenant_123" }
}Authorization 값은 설정에 직접 지정하거나 서버 URL과 일치하는 보관함 자격 증명으로 제공하세요. 두 방식 중 하나만 사용해야 합니다. 보관함 인증과 함께 다른 헤더를 사용할 수 있습니다. 세션 환경에서 시작하는 HTTP 연결은 보관함 자격 증명을 사용하지 않으므로 인증 정보를 직접 지정하거나 신뢰할 수 있는 프록시를 사용하세요.
재사용 가능한 에이전트 정의, 플러그인 아카이브, 로그에는 비밀 정보를 포함하지 마세요. 에이전트가 생성한 코드에서 자격 증명에 접근하지 못하게 하려면 환경 외부에서 자격 증명을 제공하는 신뢰할 수 있는 프록시 또는 서버를 사용하세요.
도구 접근 및 서버 시작 제어하기
allowed_tools를 설정하면 에이전트가 검색하고 호출할 수 있는 도구를 제한할 수 있습니다. 서버 초기화 실패 시 해당 턴도 실패로 처리하려면 required: true를 설정하세요. 기본적으로 서버 초기화는 필수가 아닙니다.
모든 MCP 구성 필드는 세션 생성 API 레퍼런스에서 확인하세요.
연결 문제 해결하기
필수 서버를 초기화할 수 없으면 agent.session.turn.failed에서 오류를 확인하세요. stdio 서버라면 MCP 프로세스 로그도 확인하세요.
- 네트워크 접근: URL과
connection_origin을 확인하세요. 세션 환경에서 연결하는 경우 실행기가 연결되어 있는지, 실행기의 네트워크에서 서버에 접근할 수 있는지 확인하세요. - 자격 증명: 토큰 또는 헤더를 확인하세요. 보관함을 사용하는 경우 자격 증명이 서버 URL과 일치하는지 확인하세요.
- 실행 파일 및 종속성: 설정한 명령어가 세션 환경에서 실행되는지 확인하세요.
- 작업 디렉터리: stdio 연결을 인라인으로 구성할 때는
cwd에 실제로 존재하는 디렉터리의 절대 경로를 지정하세요.