MCP를 사용하여 Cursor에 무료 웹 검색 추가하기 (API 키 불필요)
Cursor의 에이전트는 사용자의 코드베이스를 알고 있지만, 도구를 제공하지 않으면 오늘 날짜의 문서, 릴리스 노트 또는 오류 스레드를 확인할 수 없습니다. 이 가이드에서는 API 키, 회원가입 또는 확장 프로그램 없이 mcp.json 파일에 단 하나의 항목만 추가하여 Cursor MCP 웹 검색을 설정하는 방법을 다룹니다. 전역 구성과 프로젝트 구성을 비교하고, 도구 승인 방법, 지갑 키를 git에서 제외하는 방법, 그리고 Windows 수정 사항까지 다룰 것입니다. 선택적인 지갑 키는 나중에 유료 페이지 추출 및 렌더링 기능을 추가하지만, 기본적으로 검색 기능은 무료로 유지됩니다.
저희는 npm에서 @agentsearchhq/agentsearch-mcp 패키지로 배포되며 공식 MCP 레지스트리에 등재된 AgentSearch를 사용할 것입니다. 이 도구는 기본적으로 Cursor에 무료 agentsearch_web_search 도구를 제공합니다:
무료 등급: IP당 하루 최대 25회 검색, 키 필요 없음 (공유 일일 용량; 유료 호출은 제한 없음).
테스트 내용: 저희는 도구 목록, 무료 검색, 추출(Extract) 및 렌더링(Render)에 대한 지갑 관련 메시지 여부, 그리고 사용 한도까지 확인하기 위해 Linux 환경에서 Node.js 20을 사용하여 @agentsearchhq/agentsearch-mcp 1.3.5를 raw stdio로 실행했습니다. 아래의 모든 구성은 Cursor CLI (agent 2026.10.22)와 함께 로드되었으며, 이 CLI는 에디터가 사용하는 것과 동일한 mcp.json 파일을 읽습니다. 언급된 에디터 화면들은 Cursor의 문서를 참고했습니다.
Claude Code도 사용하나요? MCP를 사용하여 Claude Code에 웹 검색 추가하기를 확인하세요.
전제 조건 (Prerequisites)
- Cursor가 설치되어 있고 로그인된 상태여야 합니다.
- PATH에
npx가 있는 Node.js 20 이상 버전 (node -v)이 필요합니다. Cursor는 npx로 서버를 시작하며, 문서를 보면 해당 명령어가 시스템 경로에 있거나 전체 경로여야 한다고 명시되어 있습니다.
단계 1: AgentSearch 서버를 mcp.json에 추가하기
Cursor는 두 개의 파일에서 MCP 서버를 읽습니다:
| 파일 | 범위 | 용도 |
|---|
~/.cursor/mcp.json | 전역(Global): 사용자의 모든 프로젝트에서 적용됨 | 어디서든 필요한 도구, 그리고 비밀 정보가 포함된 모든 것 |
프로젝트 루트의 .cursor/mcp.json | 프로젝트: 이 저장소에만 적용됨 | Git을 통해 팀원들과 공유하고 싶은 도구들 |
웹 검색의 경우 일반적으로 모든 곳에서 사용하기를 원하므로, ~/.cursor/mcp.json (Windows에서는 %USERPROFILE%\.cursor\mcp.json) 파일을 생성하거나 열고 다음 내용을 추가하세요:
{
"mcpServers": {
"agentsearch": {
...
만약 파일에 이미 서버가 정의되어 있다면, 기존 mcpServers 객체 안에 "agentsearch" 블록을 추가하십시오.
agentsearch는 Cursor와 CLI에서 표시되는 서버 이름입니다."type": "stdio"는 Cursor에게 해당 서버를 로컬 프로세스로 시작하여 표준 입력(stdin)/표준 출력(stdout)을 통해 통신하도록 지시합니다. 포트, URL 또는 OAuth가 필요하지 않습니다.command와 args는 npx -y @agentsearchhq/agentsearch-mcp를 실행합니다. 여기서 -y 옵션은 npx의 설치 프롬프트를 건너뛰게 하는데, 이는 백그라운드 프로세스에서 아무도 응답할 수 없기 때문입니다.
무료 검색에는 env 블록이 필요하지 않습니다.
2단계: 팀원과 공유하기 (프로젝트 설정)
웹 검색 기능을 저장소에 커밋하여 모든 팀원이 사용할 수 있도록 하려면, 동일한 JSON을 프로젝트 루트의 .cursor/mcp.json에 넣고 파일을 커밋하십시오.
Cursor CLI를 통해 확인한 두 가지 사항이 있습니다:
- 프로젝트 서버는 승인이 필요합니다. CLI에서 새로운 프로젝트 서버가
not loaded (needs approval)로 표시되며, agent mcp enable agentsearch 명령어로 승인하기 전까지는 작동하지 않습니다. 따라서 클론된 저장소는 사용자의 허가 없이는 프로세스를 시작할 수 없습니다.
- 프로젝트 설정이 우선합니다. 두 파일(전역 및 프로젝트) 모두에
agentsearch라는 서버가 정의되어 있을 경우, 프로젝트 사본이 로드됩니다. Cursor의 CLI 문서는 순서를 프로젝트 > 전역 > 중첩된 구성 순으로 설명하고 있습니다.
절대로 지갑 키를 커밋되는 프로젝트 파일에 넣지 마십시오. 대신 참조하는 방법은 5단계에서 보여줍니다.
3단계: Cursor가 서버를 인식하는지 확인하기
에디터에서 사이드바의 Customize 메뉴를 여세요. Cursor 문서에 따르면 이곳이 MCP 서버를 활성화하거나 비활성화하는 곳이며, 각 서버는 토글 스위치를 가지고 있습니다. agentsearch가 켜져 있는지 확인하십시오.
Cursor CLI가 설치되어 있다면 터미널에서도 확인할 수 있습니다:
도구를 확인하려면 다음 명령어를 사용하세요:
agent mcp list-tools agentsearch
Tools for agentsearch (5):
- agentsearch_extract (url, formats, max_chars)
- agentsearch_render (url, formats, max_chars, screenshot, screenshot_format, full_page, viewport, wait_until, wait_for_selector, wait_ms, block)
...
다섯 가지 도구의 기능은 다음과 같습니다:
agentsearch_web_search: 최대 5개의 결과(제목, URL 및 페이지 텍스트 단락)를 반환하는 웹 검색입니다. 설정 없이 무료로 사용할 수 있습니다.agentsearch_extract: URL을 읽어 깨끗한 마크다운 또는 텍스트를 반환합니다. 유료이며 지갑(wallet)이 필요합니다.agentsearch_render: 헤드리스 브라우저에서 JavaScript가 많이 포함된 페이지를 로드하여 마크다운, 텍스트, HTML, 링크 또는 스크린샷을 반환합니다. 유료이며 지갑(wallet)이 필요합니다.agentsearch_review_lookup 및 agentsearch_review_submit: 웹 도구에 대해 에이전트가 작성한 리뷰를 읽고 공유합니다. 이들은 무료입니다.
4단계: Cursor의 에이전트에서 웹 검색 사용하기
Cursor 문서에 따르면, 에이전트는 관련성이 있을 때 사용 가능한 도구(Available Tools) 목록에 있는 MCP 도구를 자체적으로 사용하며, 여기에는 Plan Mode가 포함됩니다. 또한 이름으로도 도구를 요청할 수 있습니다. 다음과 같은 프롬프트가 효과적입니다:
Search the web for the current stable version of Next.js and tell me whether package.json is behind.
Use agentsearch to find the official migration guide for ESLint flat config, then list what we need to change in our .eslintrc.
도구 승인(Tool approval). 기본적으로 Cursor는 MCP 도구를 실행하기 전에 사용자에게 승인을 요청합니다. 도구 이름 옆의 화살표를 클릭하여 인수를 확인하세요. 검색의 경우 쿼리(query)와 max_results만 있습니다. MCP 도구는 터미널 명령어와 동일한 실행 모드(Run Modes)를 따르므로, 원격으로 실행하는 데 익숙한 도구만 사전 승인하십시오. 검색 도구는 자체 MCP 주석에서 읽기 전용(read-only)임을 표시합니다.
max_results: 1을 사용하여 agentsearch_web_search에 실제로 호출한 결과의 간소화된 예시입니다:
{
"query": "cursor mcp",
"result_count": 1,
...
결과는 전체 페이지가 아닌 단락(passages)입니다. 전체 페이지를 사용하려면 Extract와 Render 기능을 사용하세요.
Search와 Extract는 Pocket Agentic Portal에서 호출당 $0.005의 비용이 발생합니다. 결제는 Base상의 x402 USDC 또는 Tempo상의 MPP로 이루어지며, 가입이나 API 키, 최소 금액 제한이 없습니다. Render는 JavaScript 실행 후에만 콘텐츠를 표시하는 페이지용입니다. 현재 요율은 [pricing]을 참조하세요. 호출당 결제가 생소하다면, 먼저 [x402 pay-per-call APIs for AI agents]를 읽어보세요.
MCP 서버는 Base상의 USDC를 통해 x402로 결제합니다. 사용자는 소량의 USDC만 보유하는 새롭고 전용적인 지갑의 키를 제공합니다. 이 지갑은 포털에 정확한 USDC 결제만을 서명하며 가스비(gas)로 ETH가 필요하지 않습니다.
지갑 키가 있어도 Search는 기본적으로 무료로 유지됩니다. 1.3.5 버전에서는 지갑 키가 유료 Extract 및 Render만 활성화합니다. agentsearch_web_search는 사용자가 AGENTSEARCH_MODE=paid를 설정하여 검색 자체를 유료 호출로 만들거나, 또는 AGENTSEARCH_MODE=auto를 설정하여 지갑 키가 설정될 때 유료 검색에 동의하지 않는 한 무료 등급을 유지합니다. 검색을 무료로 유지하려면 모드를 설정하지 않거나(unset), free로 설정하세요.
키를 mcp.json에 붙여넣지 마세요. Cursor의 설정은 env 값에서 ${env:NAME} 인터폴레이션(interpolation)을 지원하므로, 해당 파일에는 참조만 저장됩니다:
{
"mcpServers": {
"agentsearch": {
...
Cursor가 시작하는 환경 변수에 AGENTSEARCH_WALLET_PRIVATE_KEY를 설정하고 Cursor를 재시작한 후, 이 항목을 전역 ~/.cursor/mcp.json에 유지하세요.
지출 한도(Spend caps). 서버는 무언가를 서명하기 전에 이러한 제한 사항을 확인합니다:
AGENTSEARCH_MAX_TOTAL_ATOMIC은 서버 세션당 총 지출액으로, USDC 원자 단위(atomic units)로 측정됩니다 (100만 = $1.00). 기본값은 $1.00이며, 위의 예시는 $0.05를 설정합니다. 이는 정수여야 하며, 서버가 재시작될 때 카운트가 초기화됩니다.AGENTSEARCH_MAX_PER_CALL_ATOMIC은 호출당 상한선입니다. 이 값만 낮출 수 있습니다.
지출 한도에 도달하면, 결제하는 대신 도구가 Session spend cap reached ... Nothing was signed.를 반환합니다.
Extract가 작동하면, _"https://example.com/docs/changelog에서 내용을 추출하고 이번 달에 변경된 사항을 목록으로 작성해 줘."_와 같은 프롬프트를 시도해보세요. 단일 페이지 애플리케이션(single-page apps)의 경우, Render에게 요청하세요. AI 에이전트로부터 JavaScript 페이지 읽기에 대한 가이드에서는 각각의 경우 언제 필요한지 설명합니다.
문제 해결(Troubleshooting)
먼저 MCP 로그를 확인하세요. Cursor 문서에는 출력 패널(Output panel)(Cmd+Shift+U)을, 그 안의 드롭다운 메뉴에서 MCP Logs를 가리킵니다. 여기서는 서버 시작, 도구 호출 및 오류가 표시됩니다.
서버만 단독으로 실행해 보세요. 터미널에서 npx -y @agentsearchhq/agentsearch-mcp를 실행하세요. 정상적인 서버는 stderr에 agentsearch-mcp listening on stdio를 출력하고 입력을 기다립니다 (종료하려면 Ctrl+C). 만약 npx: command not found 또는 엔진 오류가 발생하면, Node.js 20 이상을 설치하세요. nvm이나 유사한 도구를 사용한다면, command에 npx의 전체 경로를 지정해야 합니다.
Windows. 로그에서 npx 실행이 불가능하다고 표시되면, 이를 cmd /c로 감싸세요:
{
"mcpServers": {
"agentsearch": {
...
JSON에서 윈도우 경로는 이중 백슬래시(C:\Program Files\nodejs\npx.cmd)가 필요합니다. 단일 백슬래시는 전체 파일을 무효화합니다.
파일을 편집한 후 아무것도 로드되지 않습니다. 유효한 JSON(하나의 mcpServers 객체, 꼬리 쉼표 없음)인지, Customize에서 토글이 켜져 있는지, 그리고 프로젝트 설정의 경우 승인했는지 확인하세요.
Extract는 "AGENTSEARCH_WALLET_PRIVATE_KEY가 설정되었지만 개인 키가 아닙니다"라고 표시합니다. 저희 CLI 테스트에서는 설정되지 않은 변수에 대한 ${env:...} 참조가 리터럴 텍스트 ${env:AGENTSEARCH_WALLET_PRIVATE_KEY}로 서버에 도달했습니다. Cursor가 시작되는 위치에서 해당 변수를 설정한 다음, Cursor를 다시 시작하세요. 이 경우 서명되는 것은 아무것도 없으며 검색은 계속 작동합니다.
Extract 또는 Render는 "유료 도구... 지갑이 구성되지 않았습니다"라고 표시합니다. 이는 키가 없는 상태에서는 예상되는 동작입니다. 호출된 내용은 없으며 비용이 청구되지도 않았습니다.
검색(Search)은 "AGENTSEARCH_MODE는 'free', 'paid' 또는 'auto' 중 하나여야 합니다"를 반환합니다. env의 오타를 수정하거나 해당 변수를 제거하세요.
서버 업데이트. npx -y는 캐시된 사본을 실행합니다. Cursor 문서는 최신 버전을 얻으려면 서버를 제거하고, npm cache clean --force를 실행한 다음, 다시 추가할 것을 제안합니다.
에이전트가 이러한 도구에 의존하는 경우 재시도 및 폴백 패턴은 AI 에이전트 웹 도구의 오류 처리를 참조하세요.
연결하는 다른 방법들
- Pocket Agentic Portal MCP (역시 작동합니다).
npx -y @pocket-network/agentic-portal-mcp를 실행하는 항목은 Cursor를 Pocket Agentic Portal에 연결하며, 이곳에서 AgentSearch는 나열된 서비스 중 하나입니다.
- Smithery. 서버는 Smithery에서도
agentsearchhq/agentsearch-mcp로 나열되어 있습니다.
- 일반 HTTP(Plain HTTP). Cursor를 통하지 않고 자체 코드에서 검색을 호출하려면 무료 웹 검색 API 페이지를 참조하세요.
더 많은 클라이언트와 옵션은 AgentSearch MCP 페이지에 있습니다.
자주 묻는 질문 (FAQ)
Cursor에 웹 검색을 추가하는 데 API 키가 필요한가요?
아니요. 1단계의 설정에는 키가 없고, 계정이 없으며, env 블록도 없습니다. 무료 등급(Free tier): IP당 하루 최대 25회 검색까지 가능하며, 키가 필요하지 않습니다 (공유 일일 용량; 유료 호출은 제한이 없습니다).
~/.cursor/mcp.json을 사용해야 하나요, 아니면 .cursor/mcp.json을 사용해야 하나요?
모든 프로젝트에서 사용하려는 도구나 지갑 키(wallet key)와 관련된 모든 항목에는 전역적인 ~/.cursor/mcp.json을 사용하세요. 팀 전체가 저장소(repo)에서 웹 검색을 받기를 원할 때는 프로젝트의 .cursor/mcp.json을 사용하세요. 두 설정 파일 모두 동일한 서버 이름을 정의하는 경우, 프로젝트 설정이 우선합니다.
지갑 키를 추가하면 검색에 비용이 발생하나요?