[OpenAI][Responses API] built-in tools 웹 검색, 파일 검색, MCP를 한 번에 붙일 때 tool 구조를 어떻게 나누나

카테고리 없음 2026. 7. 11. 09:11

IT 리서치 노트

[OpenAI][Responses API] built-in tools 웹 검색, 파일 검색, MCP를 한 번에 붙일 때 tool 구조를 어떻게 나누나

Responses API에 도구를 붙이기 시작하면 web search, file search, remote MCP가 모두 비슷한 "검색 확장"처럼 보여 한 배열에 몰아넣기 쉽다. 하지만 2026년 7월 11일 기준 OpenAI 공식 문서를 다시 보면 역할은 꽤 다르다. tools guide는 built-in tools인 web search와 file search, 그리고 remote MCP servers를 같은 계층에서 소개하지만, web search는 최신 공개 웹, file search는 업로드한 파일과 vector stores, remote MCP는 외부 서버에서 imported tools를 가져오는 구조다. 이 글은 세 도구를 한 번에 붙여야 하는 상황에서, 어떤 질문을 어느 도구에 먼저 맡기고 어떤 권한 경계를 남겨야 운영이 덜 꼬이는지 정리한 것이다.

1. 개요

결론부터 말하면 web search, file search, remote MCP는 같은 tools 배열에 들어가더라도 먼저 풀어야 할 질문이 다르다. 최신 공개 웹이나 정책 변경처럼 시점이 중요한 질의는 web search가 맞고, 사내 매뉴얼이나 업로드한 PDF처럼 검색 범위를 고정해야 하는 질의는 file search가 맞다. 외부 시스템의 tool 목록을 가져와 action이나 외부 문맥을 붙여야 하는 경우에만 remote MCP를 좁게 여는 편이 맞다.

즉 '도구를 많이 열수록 agent가 똑똑해진다'가 아니라 '질문마다 가장 좁은 근거 경로를 먼저 고른다'가 기본 원칙이다. 이미 Responses API란 무엇인지 정리한 허브 글이 상위 출발점을 다뤘다면, 이번 글은 그 안쪽에서 built-in tools와 remote MCP를 실제로 어떻게 나누는지에 초점을 둔다.

이 구조를 운영에 붙인 뒤 remote MCP 서버가 흔들릴 때 실제 fallback 순서를 더 좁혀 보고 싶다면, 후속 글인 remote MCP 서버 응답이 흔들릴 때 file search와 web search fallback 순서를 어떻게 나누는지 정리한 글로 이어 보면 좋다. 이 글이 tool class 경계 허브라면, 후속 글은 장애 시 어떤 근거 경로부터 먼저 다시 여는지가 중심이다. 반대로 built-in tool 둘을 같은 요청에 붙였을 때 저장 경계와 재실행 기준을 나누고 싶다면 file search와 code interpreter 로그 분리 글이 다음 분기다.

2. 어디서 실제로 막히는가

현장에서 먼저 꼬이는 지점은 세 가지다. 첫째, 최신 공개 웹을 봐야 할 질문에도 file search만 열어 두고, 사내 문서를 봐야 할 질문에도 web search를 켜 두어 답의 기준이 흔들린다. 둘째, remote MCP를 file search의 강화판처럼 생각하고 외부 서버 tool import의 권한 문제를 놓친다. 셋째, 세 도구를 전부 기본값으로 열어 두고 어떤 응답이 어느 도구를 타야 했는지 운영 로그를 남기지 않는다.

공식 문서 흐름을 다시 붙이면 경계는 비교적 분명하다. tools guide는 built-in tools와 remote MCP를 함께 소개하지만, web search guide는 공개 웹을 검색하는 도구로, file search guide는 업로드한 파일과 vector stores를 검색하는 도구로 설명한다. MCP guide는 tools 파라미터에 remote MCP server를 지정하면 API가 그 서버의 tools를 가져온다고 적는다. 즉 MCP는 검색 범위 추가가 아니라 외부 tool surface를 응답 구조 안으로 들여오는 문제다.

이 차이를 무시하면 동일한 질문에도 응답 품질이 들쭉날쭉해진다. 예를 들어 현재 가격 공지를 물어보는 질문은 file search보다 web search가 먼저여야 하고, 사내 온콜 핸드북을 물어보는 질문은 web search보다 file search가 먼저여야 한다. 또 티켓 발행이나 외부 시스템 조회처럼 실제 action 또는 연결형 문맥이 필요한 질문은 remote MCP가 필요할 수 있지만, 이때는 imported tool 목록과 approval 범위를 같이 봐야 한다.

증상: 최신 공개 정보와 사내 고정 문서 답이 한 응답 안에서 뒤섞인다.
실패: remote MCP를 단순 검색 도구 하나 더 붙이는 정도로 본다.
막힘: 어떤 질문이 어떤 tool class를 탔는지 로그에 남기지 않는다.
누락: web search, file search, MCP를 모두 기본값으로 열어 과한 surface를 만든다.

질문	먼저 볼 도구	이유
가격·정책·릴리스처럼 최신 공개 웹	web search	현재 시점의 공용 정보를 직접 본다
사내 매뉴얼·PDF·업로드한 지식	file search	검색 범위를 개발자가 고정한다
외부 시스템 조회·액션·연결형 문맥	remote MCP	외부 tool surface와 권한을 같이 다룬다

3. 실무에서 적용하는 순서

실무 적용은 다섯 단계로 자르면 가장 덜 꼬인다. 먼저 질문이 최신 공개 정보 문제인지, 통제된 문서 검색 문제인지, 외부 시스템 액션 문제인지 분리한다. 두 번째로 최신 공개 정보는 web search만 열고, 통제된 지식은 file search만 여는 기본값을 만든다. 세 번째로 external action이나 외부 시스템 문맥이 필요한 질문에만 remote MCP를 추가한다. 네 번째로 remote MCP에는 imported tool 목록을 좁게 유지한다. 마지막으로 어떤 응답이 어떤 tool class를 사용했는지 trace에 남긴다.

질문을 최신 공개 웹, 고정 지식, 외부 액션 세 부류로 나눈다.
최신 공개 정보는 web search 기본값으로 둔다.
사내 문서·업로드 파일은 file search 기본값으로 둔다.
외부 시스템 연결이 필요할 때만 remote MCP를 추가한다.
도구 사용 클래스와 imported tool 이름을 같은 trace에 남긴다.

이 순서가 실용적인 이유는 도구를 줄이는 것이 곧 답의 기준을 줄이는 일이기 때문이다. 예를 들어 사내 장애 대응 매뉴얼이 이미 file search vector store에 정리돼 있다면 web search는 오히려 혼선을 늘릴 수 있다. 반대로 새 가격 공지나 상태 페이지 변동은 file search보다 web search가 먼저여야 한다. 또 외부 티켓 시스템이나 결제 관리자 문맥을 붙일 때는 remote MCP가 맞지만, 이때는 도구 연결 자체가 곧 권한 연결이라는 점을 잊지 말아야 한다.

운영 메모 예시

question_class=public_latest|private_corpus|external_action
tools_enabled=web_search,file_search,mcp
default_tool=web_search
mcp_allowed_tools=read_pricing_audit
trace_tool_class=public_latest

실행 전에는 현재 API 요청 파일을 열어 tools 배열을 확인하고, 어떤 도구가 항상 열리는지 본다. 그다음 콘솔이나 로그에서 vector store ID, imported MCP tool 이름, web search 사용 여부를 기록하면 응답 품질이 왜 달라졌는지 나중에 설명하기 쉬워진다. 이미 prompt caching이나 reasoning summary와 usage를 보고 있다면, 그 trace에 tool class까지 더해 두는 편이 운영 복기에 훨씬 유리하다.

요청 파일에서 tools 배열과 vector store ID, MCP server URL을 먼저 점검한다.
테스트 응답 로그에 어떤 tool class가 선택됐는지 남긴다.
배포 전에 imported MCP tool 이름과 approval 범위를 다시 확인한다.

핵심은 도구를 많이 붙이는 것이 아니라, 질문마다 가장 좁은 근거 경로를 먼저 여는 것이다. 그래야 답의 기준과 권한 경계가 함께 안정된다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 OpenAI tools guide 첫머리다. 여기서는 built-in tools인 web search와 file search, 그리고 remote MCP servers를 같은 도구 계층에서 설명한다. 오늘 글의 출발점은 세 도구가 모두 "tools 배열" 안에 들어가더라도 역할은 다르다는 점이다.

OpenAI tools guide는 web search, file search, remote MCP를 같은 도구 계층으로 소개한다.

즉 새 통합에서 이 셋을 한꺼번에 붙이더라도 무작정 다 열어 두는 설계는 권장되지 않는다. 어떤 질문을 어디서 풀지, 어떤 데이터가 최신 공용 웹인지, 어떤 데이터가 사내 파일인지, 어떤 동작이 외부 서버 권한까지 필요로 하는지 먼저 갈라야 한다.

두 번째 자료는 web search guide다. OpenAI는 새 Responses 통합이라면 web_search 도구를 tools 배열에 넣어 모델이 현재 공개 웹을 조회할 수 있게 하라고 적는다. 이는 최신 문서나 공용 공지, 가격표처럼 시점이 중요한 질의의 기본 경로다.

web search guide는 새 Responses 통합에서 web_search 도구를 tools 배열로 넣는 방식을 안내한다.

따라서 이미 사내 문서로 답이 정해진 질문에 web search를 기본값으로 남기면 오히려 답이 흔들릴 수 있다. web search는 공용 최신성 문제에만 열고, 사내 사실 조회는 file search나 별도 데이터 경로로 나누는 편이 안전하다.

세 번째 자료는 file search guide다. 여기서는 file search가 업로드한 파일과 vector stores를 대상으로 semantic search와 keyword search를 수행한다고 설명한다. 즉 최신 공개 웹이 아니라, 이미 선택해 둔 지식 베이스를 일관되게 찾는 도구다.

file search는 Responses API 안에서 업로드한 파일과 vector store를 검색하는 built-in tool이다.

이 구조가 중요한 이유는 web search와 반대로 검색 범위를 개발자가 미리 고정할 수 있기 때문이다. 사내 운영 문서, 정책 PDF, 제품 매뉴얼처럼 답의 출처를 좁혀야 하는 질문이라면 file search가 우선이다.

네 번째 자료는 MCP and Connectors guide다. 여기서는 tools 파라미터에 remote MCP server를 넣으면 API가 해당 서버의 tool 목록을 가져오고, 응답 안에 mcp_list_tools 항목이 생긴다고 적는다. 이 단계부터는 단순 검색이 아니라 외부 서버 권한과 imported tool surface의 문제다.

remote MCP는 tools 배열에서 외부 서버의 tool 목록을 가져와 Responses API 안으로 들여오는 구조다.

즉 MCP는 web search나 file search의 단순 확장판이 아니다. 가져온 도구 이름, approval 정책, 서버 가시성, 네트워크 경계까지 같이 설계해야 하므로 '외부 액션 또는 외부 시스템 문맥'이 필요할 때만 좁게 붙이는 편이 맞다.

실무에서는 이 셋을 역할표로 바꿔 두는 편이 가장 유용하다. 최신 공개 웹, 사내 정적 지식, 외부 시스템 액션을 한 장으로 분리하면 어떤 질의에 어떤 도구를 기본값으로 둘지 빠르게 합의할 수 있다.

web search, file search, remote MCP를 데이터 최신성·통제 범위·권한 요구로 나눈 판단표다.

이 표처럼 보면 web search는 최신성, file search는 통제된 근거, remote MCP는 외부 도구 실행 또는 외부 시스템 문맥이라는 자리가 분명해진다. 이미 remote MCP allowed_tools 글을 봤다면, 이번 글은 그 상위에서 세 도구를 함께 묶는 허브다.

마지막 자료는 최소 요청 스켈레톤이다. 세 도구를 한 요청 안에 묶더라도 기본적으로는 필요한 도구만 열고, 사후 로그에서도 어떤 tool class를 열었는지 보이게 두는 편이 좋다.

세 도구를 동시에 붙이되 역할을 분리한 Responses 요청 스켈레톤 예시다.

이 구조는 이후 previous_response_id와 stateless replay, background mode와 webhook, Responses API 상위 허브와도 자연스럽게 연결된다.

5. 주의사항과 리스크

첫 번째 리스크는 file search가 있으니 최신 공개 웹까지 커버된다고 생각하는 것이다. 두 번째 리스크는 web search를 열어 두고도 사내 기준 문서를 여기에 기대는 것이다. 세 번째 리스크는 remote MCP imported tools를 과하게 열어 둔 채 어떤 tool 이름이 실제 들어왔는지 기록하지 않는 것이다.

운영 전에 확인할 때는 최소한 question_class, default_tool, vector_store_id, mcp_allowed_tools, trace_tool_class 다섯 칸을 같은 표에 남겨 두는 편이 좋다. 이 다섯 칸이 없으면 답 품질 문제를 모델 탓으로 돌리기 쉽다.

web search는 최신 공개 웹 질문에만 먼저 연다.
file search는 통제된 문서 검색 기본값으로 쓴다.
remote MCP는 imported tool 범위까지 함께 줄인다.

6. 결론

Responses API에서 web search, file search, remote MCP를 같이 붙일 수 있다는 사실보다 중요한 것은 셋이 푸는 질문이 다르다는 점이다. 최신 공개 웹은 web search, 통제된 파일 지식은 file search, 외부 시스템 도구와 액션은 remote MCP로 좁혀 두는 편이 운영과 권한 설계가 훨씬 덜 꼬인다. 세 도구를 한 요청에 넣더라도 가장 좁은 근거 경로를 먼저 여는 것이 핵심이다.

실제 운영에서 남는 질문은 장애가 났을 때 이 경계를 어떤 순서로 다시 여느냐다. 그 다음 단계는 remote MCP 서버 응답 흔들림에 맞춘 fallback 순서 글이 file search, web search, narrow MCP 재시도를 어떤 순서로 두는지 더 구체적으로 다룬다. 또 built-in tool끼리 묶인 요청에서 근거 검색과 계산 산출물을 어떻게 따로 저장할지까지 보고 싶다면 file search와 code interpreter 저장 경계 글이 이어진다.

최신 공개 웹은 web search로 먼저 푼다.
사내 지식은 file search로 고정한다.
외부 액션과 연결형 문맥만 remote MCP로 좁게 붙인다.

ABOUT ME

FullStack Lab FullStack Lab