가이드

모든 AI 코딩 에이전트에 MCP server 추가하기: Claude Code, Cursor, Codex, Gemini CLI, VS Code 외 8개 (2026)

각 AI 코딩 에이전트는 MCP server 설정을 어디에 두며, 어떤 명령으로 서버를 추가합니까?

대부분의 에이전트는 mcpServers 객체가 있는 JSON 파일을 읽습니다. Cursor는 .cursor/mcp.json, Claude Code는 .mcp.json, Kiro는 .kiro/settings/mcp.json, Factory Droid는 .factory/mcp.json, Junie는 .junie/mcp/mcp.json입니다. 예외는 VS Code(.vscode/mcp.json의 servers 키), Codex(~/.codex/config.toml의 [mcp_servers.NAME] 테이블), OpenCode(opencode.json의 mcp 키), Zed(설정의 context_servers), goose(config.yaml의 extensions)입니다. Claude Code, Codex, Gemini CLI, Amp, Factory Droid에는 mcp add 명령도 있습니다.

이 페이지는 영어 가이드를 번역한 것입니다. 명령어, 설정 키, 코드는 원문 그대로이며 내용이 다를 경우 영어판을 기준으로 합니다. 영어 원문 보기 → · 다른 언어: 简体中文 · 日本語 · Español · Português (Brasil)

설정 변경 소식을 가장 먼저 받아 보세요

이 도구들의 설정, 플래그, 권한 규칙이 바뀌면 주 1회 이메일(영어)로 알려 드립니다. 모든 내용은 공식 문서로 확인합니다.

빠른 답변: 에이전트별 설정 위치

  • Claude Code: 원격 서버는 claude mcp add --transport http NAME URL, 로컬 서버는 claude mcp add NAME -- COMMAND. 기본값은 local scope이며, --scope project는 공유 .mcp.json에 쓰고 --scope user는 모든 프로젝트에서 서버를 사용할 수 있게 합니다.
  • Cursor: 한 프로젝트는 .cursor/mcp.json, 모든 프로젝트는 ~/.cursor/mcp.json의 mcpServers.
  • OpenAI Codex: codex mcp add NAME -- COMMAND, 또는 ~/.codex/config.toml의 [mcp_servers.NAME] 테이블.
  • Gemini CLI: gemini mcp add NAME COMMAND. 기본적으로 프로젝트의 .gemini/settings.json에 씁니다. ~/.gemini/settings.json에 쓰려면 -s user를 추가합니다.
  • VS Code(GitHub Copilot): .vscode/mcp.json의 최상위 servers 객체, 또는 MCP: Open User Configuration으로 여는 사용자 프로필 파일.
  • GitHub의 Copilot cloud agent: 저장소 Settings > Copilot > MCP servers. mcpServers 객체가 있는 JSON을 붙여 넣습니다.
  • OpenCode: opencode.json의 최상위 mcp 키.
  • Cline: cline_mcp_settings.json의 mcpServers. CLI는 ~/.cline/data/settings/cline_mcp_settings.json에 둡니다.
  • Amp: amp mcp add NAME -- COMMAND 또는 amp mcp add NAME URL, 또는 ~/.config/amp/settings.json이나 .amp/settings.json의 amp.mcpServers.
  • Kiro: .kiro/settings/mcp.json(워크스페이스) 또는 ~/.kiro/settings/mcp.json(사용자)의 mcpServers.
  • Factory Droid: droid mcp add NAME URL_OR_COMMAND --type stdio|http|sse. ~/.factory/mcp.json에 저장됩니다. 팀은 .factory/mcp.json으로 서버를 공유합니다.
  • Junie: .junie/mcp/mcp.json(프로젝트) 또는 ~/.junie/mcp/mcp.json(사용자)의 mcpServers.
  • Zed: Zed 설정 파일의 context_servers.
  • goose: ~/.config/goose/config.yaml의 extensions 키 아래 extension, 또는 goose configure 후 Add Extension.

로컬과 원격 항목은 어디서나 거의 같습니다

로컬 서버는 에이전트가 내 컴퓨터에서 시작하고 stdio로 통신하는 명령입니다. 원격 서버는 URL입니다. 대부분의 JSON 설정에서 로컬 항목은 command, args, env를, 원격 항목은 url과 선택적 headers를 가집니다. Cursor, Kiro, Junie는 모두 mcpServers 아래에서 이 형태를 받아들입니다.

.cursor/mcp.json, .kiro/settings/mcp.json 또는 .junie/mcp/mcp.json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "remote-server": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Codex: ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

VS Code: .vscode/mcp.json

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

OpenCode: opencode.json

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"]
    },
    "remote-server": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}

다른 에이전트의 설정을 복사할 때 주의할 점

  • VS Code는 .vscode/mcp.json에서 mcpServers가 아니라 servers를 사용합니다. Cursor에서 복사한 파일은 이 키 이름을 바꿔야 합니다.
  • OpenCode는 type으로 local 또는 remote를 요구하며, command는 인수를 포함한 단일 배열입니다.
  • Gemini CLI는 SSE 서버에 url을, streamable HTTP 서버에 httpUrl을 사용합니다.
  • Cline은 type이 없는 원격 항목을 레거시 SSE로 취급합니다. 권장 transport를 쓰려면 type을 streamableHttp로 설정하십시오.
  • Copilot cloud agent는 모든 서버에 tools 배열이 필요하며(모든 도구는 ["*"] 사용), 이름이 COPILOT_MCP_로 시작하는 secret과 변수만 설정에 전달됩니다.
  • Zed는 서버를 context_servers 아래에 두며, Authorization 헤더가 없는 원격 서버는 표준 MCP OAuth 흐름을 시작합니다.
  • Codex는 JSON이 아니라 TOML입니다. 서버마다 [mcp_servers.NAME] 테이블 하나를 씁니다.

프로젝트 설정, 승인, 자동 승인

  • Claude Code는 대화형 세션에서 .mcp.json의 프로젝트 범위 서버를 사용하기 전에 승인을 요청합니다.
  • Amp는 .amp/settings.json의 서버를 실행하기 전에 amp mcp approve NAME이 필요합니다. 전역 설정의 서버는 승인이 필요 없습니다.
  • Kiro는 워크스페이스 파일과 사용자 파일을 병합하며, 워크스페이스 설정이 우선합니다. autoApprove에는 확인 없이 실행되는 도구를 나열하며, "*"는 모든 도구를 승인합니다.
  • Gemini CLI: 서버에 trust: true를 설정하면 해당 서버의 모든 도구 호출 확인을 건너뜁니다. 직접 관리하는 서버에만 사용하십시오.
  • Cline: autoApprove 배열에는 Cline이 묻지 않고 호출할 수 있는 도구를 나열합니다. 안전한 도구만 넣으십시오.
  • Factory Droid: droid mcp add로 추가한 서버는 사용자 설정에 들어갑니다. .factory/mcp.json의 프로젝트 서버는 droid mcp remove로 제거할 수 없으므로 파일을 직접 편집하십시오.

서버가 로드되었는지 확인

  • Claude Code: /mcp. OAuth 서버에 로그인하는 곳이기도 합니다.
  • Codex: TUI의 /mcp가 활성 서버를 보여 줍니다. codex mcp login NAME으로 OAuth 서버에 로그인합니다.
  • Gemini CLI: /mcp가 각 서버의 연결 상태를 보여 줍니다.
  • Factory Droid: /mcp가 대화형 관리자를 엽니다.
  • Junie CLI: /mcp가 서버와 범위, 상태를 나열합니다.
  • Amp: amp mcp doctor.

에이전트별 전체 MCP 설정 가이드

출처

이 가이드에서 확인한 공식 문서(영어)입니다. 영어판 확인일: 2026-10-18

다른 한국어 가이드