VS Code의 GitHub Copilot 에이전트는 파일을 편집하고 터미널 명령을 실행할 수 있지만, 이를 위한 도구를 제공하지 않는 한 라이브 웹에서 정보를 조회할 수는 없습니다. 이 가이드에서는 API 키나 회원가입 없이 하나의 MCP 서버 항목으로 VS Code MCP 웹 검색 기능을 추가합니다. 전체 설정은 다음과 같습니다. 워크스페이스 루트에 .mcp.json으로 저장하세요:
{
"mcpServers": {
"agentsearch": {
...
VS Code 자체 포맷을 선호하나요? 같은 서버를 .vscode/mcp.json에서 mcpServers 대신 servers를 사용합니다:
{
"servers": {
"agentsearch": {
...
두 항목 모두 npm의 @agentsearchhq/agentsearch-mcp 패키지(공식 MCP 레지스트리에서는 io.github.agentsearchhq-coder/agentsearch-mcp로도 나열됨)를 통해 AgentSearch를 실행합니다. 이는 Copilot에게 무료 agentsearch_web_search 도구를 제공합니다:
무료 등급: IP당 하루 최대 25회 검색, 키 필요 없음 (공유 일일 용량; 유료 호출은 제한 없음).
테스트 내용: Linux 및 Node.js 24 환경에서 @agentsearchhq/agentsearch-mcp 1.3.6 (npm 최신 버전)을 사용하여 공식 MCP TypeScript SDK 클라이언트가 위의 두 파일을 모두 읽고, npx를 통해 서버를 시작하며, 다섯 가지 도구를 나열하고, 실제 무료 검색을 실행했습니다. 또한 VS Code 1.144.1에서 code --add-mcp 명령을 실행하여 생성된 파일을 확인했습니다. Copilot에 로그인하지 않았기 때문에 채팅창에서 에이전트가 도구를 호출하는 것을 관찰하지는 못했습니다. 메뉴 이름은 VS Code 문서를 따릅니다.
다른 편집기를 사용하나요? Cursor, Claude Code 또는 VS Code용 Cline 확장 프로그램을 확인하세요.
전제 조건 (Prerequisites)
- GitHub Copilot 및 AI 기능이 켜져 있고 로컬 폴더가 열린 VS Code.
- PATH에
npx가 설정된 Node.js 20 이상 (node -v). 이 패키지는 Node 20 이상을 요구합니다.
단계 1: 설정 파일 위치 선택
VS Code는 상호 교환할 수 없는 두 가지 형식의 MCP 서버 파일을 읽습니다:
- Portable Copilot 형식 (최상위
mcpServers): 워크스페이스 루트에 있는 .mcp.json, 또는 사용자용으로는 ~/.copilot/mcp-config.json입니다 ($COPILOT_HOME/mcp-config.json 변수를 설정한 경우). Copilot 하네스는 이 파일들을 직접 읽으며, 사용자 파일은 GitHub Copilot CLI가 사용하는 파일이기도 합니다.
- VS Code 형식 (최상위
servers): 워크스페이스 내의 .vscode/mcp.json, 또는 사용자 프로필에 있는 mcp.json입니다. VS Code는 이 서버들을 Copilot 세션으로 전달하지만, ${input:...} 변수가 필요한 서버는 예외입니다. 안내 흐름(guided flow)은 이제 이러한 목적지들을 사용 중단 예정(deprecated)으로 표시하지만, 여전히 작동하며, 오직 이곳만이 input 변수, envFile, 그리고 샌드박싱을 지원합니다.
프로젝트와 서버를 공유하려면 .mcp.json을 사용하고, 모든 곳에서 사용하려면 ~/.copilot/mcp-config.json을 사용하거나, 팀이 이미 서버를 보관하는 경우 .vscode/mcp.json을 사용하세요. servers 파일에 mcpServers 블록을 붙여넣거나 그 반대의 경우는 하지 마세요.
2단계: AgentSearch 서버 추가하기
명령 팔레트에서. MCP: Add Server를 실행하고, **Command (stdio)**를 선택한 후 다음을 입력하세요:
npx -y @agentsearchhq/agentsearch-mcp
서버 ID는 agentsearch로 지정합니다. 개인 설정을 위해서는 Global을 선택한 다음 Copilot Global을 선택하면, 포터블 항목이 ~/.copilot/mcp-config.json에 작성됩니다.
터미널에서. code CLI는 한 줄 명령으로 서버를 VS Code 사용자 프로필에 추가합니다:
code --add-mcp '{"name":"agentsearch","type":"stdio","command":"npx","args":["-y","@agentsearchhq/agentsearch-mcp"]}'
테스트 결과, Added MCP servers: agentsearch가 출력되었고 VS Code 데이터 폴더(~/.config/Code/User/mcp.json - 리눅스 기본값)의 User/mcp.json에 servers 항목이 작성되었습니다. MCP: Open User Configuration을 사용하면 어떤 OS에서도 해당 파일을 열 수 있습니다.
수동으로. 이 게시물의 상단에서 일치하는 스니펫을 복사하여 붙여넣고 저장하세요. -y는 npx의 설치 프롬프트를 건너뛰게 하며, 무료 검색(free search)은 env 블록이 필요 없습니다. 파일에 이미 서버가 있는 경우, 그 옆에 agentsearch를 추가하고 쉼표 처리에 유의하세요. 그런 다음 JSON을 확인하세요.
python3 -m json.tool .vscode/mcp.json
후행 쉼표가 있어 다음과 같은 메시지가 출력되었습니다. Illegal trailing comma before end of object: line 6 column 55.
3단계: 신뢰 설정, 시작 및 도구 확인
워크스페이스 파일(.vscode/mcp.json 및 .mcp.json)은 워크스페이스 신뢰(Workspace Trust)를 따릅니다. 제한된 모드(Restricted Mode)에서는 서버가 시작되지 않습니다. 사용자 구성의 서버는 첫 시작 시 신뢰 여부를 요청할 수 있습니다.
**MCP: 서버 목록 보기(List Servers)**를 실행하고, agentsearch를 선택한 후, 서버 시작(Start Server) 또는 **출력 표시(Show Output)**를 선택합니다 (또는 **채팅(Chat): 사용자 정의 설정 열기 > MCP 서버(Open Customizations > MCP Servers)**를 사용합니다). 정상적인 시작은 agentsearch-mcp listening on stdio 로그를 기록합니다.
다섯 개의 도구가 표시되어야 합니다:
agentsearch_web_search: 최대 5개의 결과(제목, URL, 짧은 구절)를 반환하는 웹 검색 기능입니다. 무료이며 설정이 필요 없습니다.agentsearch_extract: URL을 읽어 깨끗한 마크다운 또는 텍스트를 반환합니다. 유료이며 지갑(wallet)이 필요합니다.agentsearch_render: 자바스크립트가 많은 페이지를 헤드리스 브라우저(headless browser)에서 로드하고 마크다운, HTML, 링크 또는 스크린샷을 반환합니다. 유료이며 지갑(wallet)이 필요합니다.agentsearch_review_lookup 및 agentsearch_review_submit: 웹 도구에 대한 에이전트 작성 리뷰를 읽고 공유합니다. 무료입니다.
검색(Search), 추출(extract), 렌더링(render), 리뷰 조회(review lookup)는 읽기 전용으로 표시됩니다. 에이전트가 사용할 수 있는 기능을 제한하려면, Copilot 하네스 세션의 경우 **채팅(Chat): 사용자 정의 설정 열기 > 도구(Open Customizations > Tools)**를 사용하거나, 로컬 세션의 경우 채팅 입력창에서 **도구 구성(Configure Tools)**을 사용합니다.
다음은 max_results: 2로 설정하여 .vscode/mcp.json 항목을 통해 실행한 실제 검색의 일부 결과입니다:
{
"query": "vs code mcp.json servers configuration",
"result_count": 2,
...
}
결과는 전체 페이지가 아닌 구절(passages)입니다. 이것이 바로 Extract와 Render의 용도입니다.
4단계: 에이전트 모드에서 검색, 추출 및 렌더링하기
채팅의 에이전트 선택기(agent picker)에서 **에이전트(Agent)**를 선택합니다. VS Code 문서는 새로운 서버를 확인할 때 프롬프트에 서버 이름을 지정하라고 안내하므로, 다음과 같이 시작합니다:
Use the agentsearch MCP server to search the web for the latest Node.js LTS release and list what changed, with links. Don't change any files.
승인 프롬프트가 나타나면 쿼리를 확인하고 **허용(Allow)**을 선택하세요. 그런 다음 도구 호출을 확장하여 답변이 그 출력에서 왔는지 확인합니다.
검색은 또한 에이전트가 학습 데이터보다 더 최신 정보를 접할 때 작업 중간에도 도움이 됩니다:
The build fails with this bundler error. Search the web for it and suggest a fix that matches the version in package.json.
단락만으로는 충분하지 않을 때는 전체 페이지를 요청하세요:
Extract the first link as markdown and summarize the migration steps.
이것이 Extract입니다. 페이지가 싱글 페이지 앱(single-page app)이고 Extract 결과가 부실하면 Render를 요청하세요:
That docs page builds its content with JavaScript. Render it and pull the config options into a list.
채팅 입력창에 #을 입력하여 도구를 직접 참조할 수도 있습니다. 지갑(wallet)이 없으면 Extract와 Render는 No wallet is configured, so no call was made.라고 답변합니다. 비용은 청구되지 않으며 검색 기능은 계속 작동합니다. AI 에이전트로부터 JavaScript 페이지 읽기에 대한 저희 가이드에서 각각 언제 사용해야 하는지 설명합니다.
Search와 Extract는 호출당 $0.005의 비용이 들며, x402를 통해 USDC로 결제됩니다. 가입이나 API 키, 최소 금액 제한이 없습니다. Render는 JavaScript 실행 후에만 콘텐츠를 표시하는 페이지용입니다. 현재 요금은 pricing을 참조하세요.
서버는 소량의 USDC만 보유한 **새롭고 전용적인 지갑(dedicated wallet)**의 키를 사용하여 Base상의 Pocket Network Agentic Portal을 통해 결제합니다. 이 키를 커밋하는 파일에 작성하지 마십시오. 포터블 형식에서는 대신 환경 변수를 참조하세요:
{
"mcpServers": {
"agentsearch": {
...
VS Code 문서를 따르면, 해당 변수를 서버를 실행하는 호스트의 환경 변수에 설정하고 중괄호 ${NAME} 형식을 사용해야 합니다. 대신 .vscode/mcp.json에서는 "password": true를 가진 promptString 입력을 사용하여 ${input:...}으로 참조할 수 있습니다. VS Code는 한 번 프롬프트를 표시하고 값을 저장하지만, 입력이 필요한 서버는 Copilot harness 세션으로 전달되지 않으므로 로컬(Local) 세션에서만 작동합니다. 변경 사항이 있을 때마다 서버를 다시 시작하세요.
지갑 키가 있어도 검색은 기본적으로 무료로 유지됩니다. 1.3.6 버전에서는 해당 키가 유료 Extract 및 Render 기능만 활성화합니다. agentsearch_web_search는 AGENTSEARCH_MODE를 paid(또는 auto)로 설정하지 않는 한 무료 등급에 머무릅니다.
지출 상한액 (Spend caps). 서버는 무언가를 서명하기 전에 다음 항목들을 확인합니다:
AGENTSEARCH_MAX_TOTAL_ATOMIC은 USDC 원자 단위로 서버 세션당 총 지출액을 제한합니다 (1,000,000 = $1.00). 기본값은 $1.00이며, 예시에서는 $0.05로 설정합니다. 이 값은 서버가 재시작될 때 초기화됩니다.AGENTSEARCH_MAX_PER_CALL_ATOMIC은 호출당 상한선입니다. 이 값만 낮출 수 있습니다.
상한액을 0으로 설정하고 자금이 공급되지 않은 테스트 키를 사용했을 때, Extract는 Session spend cap reached ... Nothing was signed.를 반환했습니다.
문제 해결 (Troubleshooting)
서버를 단독으로 실행해 보세요. 터미널에서 npx -y @agentsearchhq/agentsearch-mcp를 실행합니다. 이 경우 listening on stdio 라인을 출력하고 대기해야 합니다. 여기서 실패한다면, VS Code 역시 이를 시작할 수 없습니다.
출력을 확인하세요. MCP: List Servers > agentsearch > Show Output에서 정확한 오류를 확인할 수 있습니다.
서버가 나타나지 않습니다. 최상위 키가 파일과 일치하는지 확인하세요 (.mcp.json 및 ~/.copilot/mcp-config.json의 경우 mcpServers, mcp.json의 경우 servers). 또한, 작업 공간이 신뢰되는지(trusted) 그리고 서버가 Copilot 세션에서 ${input:...} 변수에 의존하지 않는지도 확인해야 합니다. 조직 정책(Organization policy) 역시 서버를 차단할 수 있습니다.
npx를 찾을 수 없음(not found).Node.js 20 이상을 설치하세요. 버전 관리자를 사용하는 경우 VS Code가 셸의 PATH를 상속받지 못할 수 있으므로,which npx의 출력을 command`에 넣어주세요. 원격 창이나 dev container에서는 서버가 실행되는 곳에 Node가 설치되어야 합니다.
에이전트가 도구를 호출하지 않습니다(The agent doesn't call the tool). 프롬프트에서 단계 4와 같이 서버 이름을 지정하고, Tools에서 활성화되었는지 확인하세요.
재시도 및 폴백(fallback) 패턴에 대해서는 AI 에이전트 웹 도구 오류 처리를 참조하세요.
더 많은 클라이언트는 AgentSearch MCP 페이지에 있으며, AI 에이전트를 위한 MCP 웹 검색에서 더 큰 그림을 다룹니다.
FAQ
VS Code에 웹 검색 기능을 추가하는 데 API 키가 필요한가요?
아니요. 상단의 항목들은 키, 계정 또는 env 블록이 없습니다. 무료 등급(Free tier): IP당 하루 최대 25회 검색까지 가능하며, 키가 필요하지 않습니다 (공유 일일 용량; 유료 호출은 제한 없음).
.mcp.json을 사용해야 하나요, 아니면 .vscode/mcp.json을 사용해야 하나요?
현재 VS Code 문서는 새로운 설정을 포터블 파일로 안내합니다: 팀용 워크스페이스 루트의 .mcp.json, 본인용 ~/.copilot/mcp-config.json입니다. .vscode/mcp.json도 여전히 작동하며, VS Code가 이를 Copilot 세션으로 전달합니다. 입력 변수(input variables), envFile, 또는 샌드박싱이 필요한 경우 사용하세요.
GitHub Copilot CLI와 함께 작동하나요?
Copilot CLI는 Copilot Global이 작성하는 것과 동일한 파일인 ~/.copilot/mcp-config.json을 읽기 때문에, 하나의 항목으로 둘 다 커버됩니다. 저희가 CLI를 테스트하지는 않았습니다.
지갑 키(wallet key)를 추가하면 검색 비용이 발생하나요?
기본적으로는 그렇지 않습니다. 1.3.6 버전에서는 AGENTSEARCH_MODE=paid (또는 auto)일 때만 $0.005의 유료 호출로 검색을 만듭니다. Extract와 Render가 지갑을 사용하는 호출입니다.
검색은 몇 개의 결과를 반환하나요?
호출당 최대 5개까지 반환합니다. 에이전트는 max_results를 사용하여 더 적은 개수를 요청할 수 있습니다 (1~5).
이미 Cursor 또는 Claude Desktop에 AgentSearch를 설정했습니다. VS Code가 이를 재사용할 수 있나요?
네. chat.mcp.discovery.enabled 설정은 VS Code가 Claude Desktop, Cursor, Windsurf, 그리고 GitHub Copilot CLI로부터 MCP 설정을 읽을 수 있게 합니다. Copilot CLI 검색 기능은 기본적으로 활성화되어 있으며, 나머지 도구들은 사용자가 직접 켜기 전까지는 비활성화되어 있습니다.
에이전트가 웹 페이지를 읽게 하는 것이 안전한가요?
웹 콘텐츠는 신뢰할 수 없는 입력으로 취급하세요. 페이지에는 AI를 유도하기 위해 작성된 텍스트가 포함될 수 있습니다. 파일을 편집하거나 명령을 실행하는 도구에 대해서는 승인 설정을 유지하세요.
시작하기
.mcp.json 또는 .vscode/mcp.json에 agentsearch 항목을 추가하고, 워크스페이스를 신뢰하며, 다섯 가지 도구에 대해 MCP: List Servers에서 확인한 후, Copilot 에이전트에게 이번 주에 변경된 내용에 대해 질문하세요. 전체 페이지가 필요할 때는 Extract와 Render를 위한 제한된 지갑을 추가하세요. pricing 및 MCP 설정 페이지를 참조하거나, AgentSearch 블로그에서 더 많은 가이드를 찾아보세요.
원래 AgentSearch 블로그에 게시되었습니다.