기존 Agent에 Parallel Search MCP 연결하기: 검색 키 없는 웹 검색·원문 가져오기·비용 경계
기존 코딩 또는 리서치 Agent에 호스팅 웹 검색과 페이지 원문 가져오기를 추가하는 검증 가능한 안내입니다. 검색 API Key가 필요 없는 익명 endpoint로 시작해 연결 상태, 실제 web_search/web_fetch tool call, 출처 URL을 확인한 뒤 익명 한도, Bearer/OAuth, Parallel 과금, 클라이언트 구독, 모델 API token 비용을 별도로 판단합니다.
목차
Parallel Search MCP는 검색 서버를 직접 운영하거나 별도의 검색 API Key를 신청하지 않고도 기존 코딩·리서치 Agent에 추가할 수 있습니다. 호스팅 Streamable HTTP endpoint https://search.parallel.ai/mcp는 Agent에 web_search와 web_fetch 두 도구를 제공합니다.
설정이 저장됐다는 사실만으로는 동작을 증명할 수 없습니다. 연결 상태, 두 도구의 노출 여부, 대화에서 발생한 실제 tool call, 열 수 있는 출처 URL까지 확인해야 합니다. 아래 내용은 2026년 10월 11일에 연 공식 문서를 기준으로 작성한 재검증 절차이며, 최종 판단은 자신의 client log와 billing page에서 해야 합니다.
먼저 endpoint와 인증 방식을 선택하기
| 목적 | Endpoint | 인증 | 적합한 경우 |
|---|---|---|---|
| 검색과 원문 가져오기를 먼저 검증 | https://search.parallel.ai/mcp | 없음 | 낮은 익명 rate limit으로 가볍게 시험 |
| 계정 credits와 더 높은 limit 사용 | https://search.parallel.ai/mcp | Bearer API Key | 반복 작업 또는 production workload |
| 브라우저 로그인을 client가 처리 | https://search.parallel.ai/mcp-oauth | OAuth 또는 Bearer API Key | 고정 key를 공유 설정에 두지 않으려는 경우 |
기본 /mcp endpoint는 OAuth를 광고하지 않으므로 OAuth 지원 client도 브라우저를 열지 않고 익명으로 연결할 수 있습니다. /mcp-oauth는 인증이 필수이며 익명 요청에는 401을 반환합니다. 따라서 /mcp에서 로그인 창이 뜨지 않는 것은 실패가 아닙니다. /mcp-oauth의 401은 대개 인증이 완료되지 않았다는 뜻입니다.
Client, 웹 도구, 모델 Provider를 분리하기
하나의 답변에는 서로 독립적인 세 경로가 들어갈 수 있습니다.
- Agent client가 대화, 권한, 도구 선택, UI를 관리합니다.
- Parallel Search MCP가
web_search와web_fetch를 실행합니다. - 모델 Provider가 추론하고 입력·출력·tool result context token을 계산합니다.
MCP를 추가해도 모델 Base URL은 바뀌지 않습니다. 모델 API를 변경해도 웹 검색이 자동으로 생기지 않습니다. 장애를 볼 때는 “MCP에 연결됐는가”, “실제로 도구를 호출했는가”, “모델 요청을 누가 과금했는가”를 각각 확인해야 합니다.
Claude Code: 익명 endpoint로 최소 연결
Claude Code를 사용하는 프로젝트에서 실행합니다.
claude mcp add --transport http "Parallel-Search-MCP" https://search.parallel.ai/mcp
claude mcp get "Parallel-Search-MCP"
claude mcp list기본값은 local scope입니다. 모든 프로젝트에서 의도적으로 사용하려면 --scope user를 추가합니다. 팀이 공유하는 .mcp.json은 commit 전에 검토하고 고정 Bearer token을 넣지 마십시오.
Claude Code 안에서는 MCP panel을 엽니다.
/mcpAdded는 설정이 기록됐다는 뜻일 뿐입니다. 현재 client가 server에 도달한다는 신호는 Connected입니다. OAuth가 필요하면 URL을 다음으로 바꿉니다.
https://search.parallel.ai/mcp-oauth그다음 /mcp에서 인증을 완료합니다. /mcp와 /mcp-oauth 오류를 같은 문제로 섞어 판단하지 마십시오.
Codex CLI: 익명, 환경 변수 Bearer, OAuth
익명 설정:
codex mcp add parallel-search --url https://search.parallel.ai/mcp
codex mcp list계정 기반 limit이 필요하면 PARALLEL_API_KEY를 OS 또는 secret manager에 안전하게 저장합니다. 실제 key를 shell history나 공유 config에 쓰지 말고 Codex에는 환경 변수 이름만 전달합니다.
codex mcp add parallel-search --url https://search.parallel.ai/mcp \
--bearer-token-env-var PARALLEL_API_KEY
codex mcp listOAuth 설정:
codex mcp add parallel-search --url https://search.parallel.ai/mcp-oauth
codex mcp list추가 후에는 새 Codex session을 시작합니다. 다른 MCP client도 같은 endpoint를 쓸 수 있지만 설정 schema는 다릅니다. VS Code는 최상위 servers, Cursor는 일반적으로 mcpServers를 사용하며 일부 client는 type: "streamable-http"를 요구합니다. 한 client의 JSON을 다른 제품에 그대로 복사하지 마십시오.
실제로 어떤 도구를 호출했는지 증명하기
연결 상태는 도달 가능성만 증명합니다. 특정 답변에서 Parallel을 썼는지 확인하려면 관찰 가능한 흔적을 남기는 prompt가 필요합니다.
이번 확인에서는 반드시 Parallel-Search-MCP를 사용하고 기억만으로 답하지 마세요.
1. web_search를 호출해 Parallel Search MCP 공식 문서와 현재 가격 페이지를 찾으세요.
2. web_search가 반환한 출처 URL을 보여 주세요.
3. 공식 URL 두 개를 선택하고 web_fetch를 호출해 원문을 읽으세요.
4. 각 출처에 대해 도구 이름, URL, 짧은 근거 문장을 제시하세요.
도구 호출이 실패하면 중단하고 도구 이름, endpoint, HTTP status를 보고하세요.이후 네 가지를 확인합니다.
- tool trace에
web_search가 있습니다. - 검색 snippet 요약만이 아니라 뒤이어 별도의
web_fetch가 있습니다. - tool result에 실제로 열 수 있는 URL이 있습니다.
- 최종 주장이 fetch된 페이지 원문에서 확인됩니다.
“웹에서 검색했다”는 문장은 증거가 아닙니다. client가 내장 Web Search를 잠시 끌 수 있다면 이 분리 테스트 동안만 비활성화해 비슷한 기능을 혼동하지 않도록 합니다.
먼저 검색하고, 선택한 원문을 가져오기
공식 역할 구분은 명확합니다.
web_search는 최신 정보와 여러 출처를 찾으며objective와search_queries가 필수입니다.web_fetch는 알려진 URL 또는 선택한 검색 결과를 읽고 한 요청에 최대 20 URLs를 받습니다.
Client가 tool arguments에 영향을 줄 수 있다면 다음 순서를 사용합니다.
objective는 “공식 익명 인증 규칙과 비용 경계를 확인한다”처럼 하나의 판단으로 좁힙니다.- 짧고 상호 보완적인
search_queries두세 개를 사용하고 긴 prompt 전체를 넣지 않습니다. - 같은 대화에서는 같은
session_id를 재사용하고 새 대화에서는 새 값을 만듭니다. - 처음에는
full_content: false를 유지합니다. 전체 페이지는 수만 개 모델 token을 쓸 수 있고 client 출력 limit을 넘을 수 있습니다. - 공식 문서, 사양, 원문 발표를 우선합니다. 커뮤니티 글은 사용자 보고로 표시하고 보편적 동작으로 확대하지 않습니다.
검색 → URL 선택 → 원문 fetch → 인용 확인의 흐름은 단순히 “인터넷에서 찾아라”라고 하는 것보다 감사하기 쉽습니다.
비용 경계: 최소 네 개 장부로 나누기
아래 단가는 2026년 10월 11일 Parallel 공식 가격 페이지에서 확인했습니다. 비용 구조를 구분하기 위한 것이며 어느 선택이 항상 더 저렴하다는 뜻은 아닙니다.
| 비용 층 | Subscription 또는 membership | Minimum top-up | First-month allowance | Usage basis |
|---|---|---|---|---|
| 익명 Search MCP | 문서화된 익명 설정은 계정 subscription을 요구하지 않음 | 익명 시작에 top-up 불필요 | 고정 call 수가 공개되지 않음 | 탐색·가벼운 사용에 free로 설명되지만 limit은 낮음 |
| 인증된 Parallel Search/Extract | 공개 가격 페이지에 별도 membership fee가 명시되지 않음 | 명시되지 않음 | 고정 초기 credit 명시 없음 | Search 기본 요금(요청당 결과 10개 포함): fast/turbo 1,000 requests당 US$1, basic/advanced US$5, 추가 페이지 결과 및 발췌문은 결과 1,000개당 US$1, Extract는 1,000 URLs당 US$1 |
| Agent client | Claude Code, Codex 또는 다른 client 계약에 따름 | Client-specific | Client-specific | Client plan 혜택은 Parallel credits가 아님 |
| 모델 API | Provider-specific | Provider-specific | Provider-specific | 입력, 출력, cache, tool result context는 Search MCP와 별도 과금 |
Search MCP 페이지는 익명 모드의 고정 숫자 quota를 공개하지 않습니다. “lower rate limits”를 임의로 “하루 N회 무료”라는 약속으로 바꾸면 안 됩니다. 일반 Search API rate-limit 표도 익명 MCP에 대한 보장이 아닙니다.
인증 연결에서 402가 나오면 Parallel 문서는 credits 부족으로 설명합니다. 반복 retry 전에 잔액과 현재 연결 모드를 확인하십시오.
BetterToken을 모델 Provider로 써도 설정은 독립적
Claude Code 또는 Codex가 이미 BetterToken으로 모델 요청을 보내고 있다면 기존 client를 유지하고 Parallel만 웹 도구 층으로 추가할 수 있습니다.
- Claude Code 모델 Base URL은
https://bettertoken.ai이며 client가/v1/messages를 추가하므로/v1을 직접 붙이지 않습니다. - Codex 모델 Base URL은
https://www.bettertoken.ai/v1이고wire_api = "responses"를 사용합니다. - Parallel tool URL은 계속
https://search.parallel.ai/mcp또는https://search.parallel.ai/mcp-oauth입니다.
이 URL들은 서로 바꿀 수 없습니다. BetterToken은 모델 요청과 token usage를, Parallel은 웹 도구를 담당합니다. 익명 가용성, credits, privacy, limit은 외부 서비스 자체 규칙을 따릅니다. Claude Code 연결 문서, Codex 연결 문서, Parallel Search MCP 공식 문서를 각각 확인하십시오.
흔한 실패와 최소 재검증
| 증상 | 먼저 확인 | 수정 후 검증 |
|---|---|---|
| Server를 추가했지만 tools가 없음 | client 완전 재시작, config 문법, 정확한 URL, MCP logs | web_search와 web_fetch가 보임 |
401 | /mcp-oauth 사용 여부, OAuth 완료, Bearer 유효성 | 재연결 후 인증 요구가 사라짐 |
402 | 인증 계정 credits | 잔액 추가 또는 익명 /mcp로 돌아가 좁은 검색 실행 |
| Connected지만 tool call 없음 | Agent가 내장 검색이나 기억을 선택했을 수 있음 | 강제 test prompt를 실행하고 trace 확인 |
| Fetch 결과가 너무 크거나 잘림 | full_content, URL 수, 넓은 objective | 전체 내용을 끄고 필요한 페이지만 fetch |
| 프로젝트마다 동작이 다름 | Claude Code scope, project approval, 오래된 Codex session | 대상 project에서 server list와 강제 call 반복 |
장기 사용을 결정하는 기준
자체 SearXNG 같은 검색 인프라를 유지하지 않고 호스팅 검색과 원문 읽기가 필요하며, client가 tool call과 출처를 보여 주고, 익명 한도가 가벼운 작업에 충분하거나 인증 사용 예산을 세울 수 있다면 장기 사용에 적합합니다.
공개적으로 보장된 고정 무료 횟수가 필요하거나, 익명 상태에서 조직 귀속 또는 Zero Data Retention이 필수이거나, 실제 tool call을 확인할 수 없거나, index·crawler·data residency를 완전히 통제해야 한다면 바로 production에 넣지 마십시오.
가장 안전한 순서는 익명 /mcp로 대표 작업을 실행하고 tool trace와 출처 URL을 저장한 뒤 rate-limit 동작과 모델 token 증가를 측정하는 것입니다. 익명 제한이 실제 병목이 된 경우에만 Bearer 또는 /mcp-oauth로 전환하면 연결, 검색 품질, 외부 비용, 모델 비용을 분리해 검증할 수 있습니다.
