MCP JSON 설정 파일: mcp.json 구조와 클라이언트별 차이

MCP JSON 설정 파일은 MCP 클라이언트에게 어떤 서버를 쓸지 알려 줍니다. 최상위 객체는 서버 이름마다 항목 하나를 대응시킵니다. 로컬 서버 항목에는 command와 args, 그리고 선택적으로 env가 들어가고, 원격 서버 항목에는 URL과, 키가 필요하면 headers가 들어갑니다. 클라이언트들은 이 구조에는 동의하지만 키 이름은 서로 다릅니다. Cursor와 Claude Code가 mcpServers를 쓰는 자리에 VS Code는 servers를 쓰고, Android Studio는 URL을 httpUrl이라고 부르므로, 각 항목은 그 파일을 읽는 클라이언트에 맞춰 작성하세요.

키 이름은 각 클라이언트의 자체 문서인 Cursor, Claude Code, VS Code, GitHub Copilot CLI, JetBrains IDE의 Copilot, Android Studio 문서와 MCP 문서의 Claude Desktop 예시에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume 항목은 Sume의 MCP 빠른 시작과 OAuth와 API 키 페이지에서 가져왔습니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명하며, Sume에는 이 클라이언트들을 위한 전용 커넥터가 없습니다. 각 항목은 일반적인 원격 MCP 연결입니다.

mcp.json 파일이란 무엇인가요?

클라이언트가 MCP 서버 목록을 읽어 오는 파일입니다. 아래 첫 번째 항목은 MCP 문서의 Claude Desktop 예시로, npx로 시작하는 파일 시스템 서버이며 이 서버가 쓸 수 있는 폴더를 args로 넘깁니다. 두 번째는 Sume 빠른 시작이 Cursor용으로 제시하는 원격 항목으로, URL 하나뿐입니다.

// Local server: Claude Desktop's claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

// Remote server: Cursor's mcp.json, from Sume's quickstart
{
  "mcpServers": {
    "sume": { "url": "https://mcp.sume.com/mcp" }
  }
}

MCP 설정은 왜 클라이언트마다 다른가요?

클라이언트마다 자체 파일 형식을 정의하므로, 복사해 온 항목이 키 이름 때문에 실패할 수 있습니다. 원격 서버 기준으로 정리하면 다음과 같습니다.

설정 파일 하나를 여러 클라이언트에서 쓸 수 있나요?

부분적으로는 가능합니다. 최상위에 mcpServers 객체가 있는 .mcp.json 파일은 Claude Code의 프로젝트 파일이자, Copilot CLI가 불러오는 프로젝트 파일 중 하나이며, VS Code가 이식 가능한(portable) 형식이라고 부르는 파일입니다. 원격 항목에는 모두 "type": "http"를 넣으세요. Claude Code는 type이 없는 항목을 stdio 서버로 읽으므로, url만 있으면 설정 오류가 됩니다. Sume용 항목은 다음과 같습니다.

{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp"
    }
  }
}

MCP 설정에서 API 키는 어디에 넣나요?

커밋하는 파일에는 넣지 마세요. Sume 빠른 시작은 인터랙티브 클라이언트에 OAuth를 권장합니다. 헤더가 없는 항목이면 클라이언트가 Sume 로그인을 실행하고, Sume 동의 페이지에서 Write는 직접 켜지 않는 한 꺼진 채로 남습니다. OAuth를 쓰지 않는 자동화에는 Sume가 Authorization: Bearer $SUME_API_KEY나 x-api-key를 받습니다. 키를 붙여 넣지 말고 클라이언트의 변수 문법으로 참조하세요.

• Claude Code는 url과 headers를 포함해 .mcp.json 안의 ${VAR}와 ${VAR:-default}를 확장합니다. 예를 들어 "Authorization": "Bearer ${SUME_API_KEY}"처럼 씁니다.
• Cursor는 command, args, env, url, headers 안의 ${env:NAME}을 해석합니다.
• VS Code는 서버가 처음 시작될 때 ${input:…} 값을 입력하라고 요청한 뒤, 그 값을 안전하게 저장합니다.
• Sume 키가 로그나 채팅 기록에 노출되면 교체하세요. VS Code 버전은 VS Code 원격 MCP 서버에서 단계별로 설명합니다.

설정한 MCP 서버가 왜 로드되지 않나요?

먼저 클라이언트별 규칙을 확인하세요.

• Claude Code는 url은 있지만 type이 없는 항목의 서버를 건너뛰고, 오류 메시지로 그 사실을 알려 줍니다.
• Copilot CLI는 .vscode/mcp.json을 읽지 않습니다. 그 파일의 최상위 servers 키를 Copilot CLI에서는 지원하지 않습니다.
• Copilot CLI는 폴더 신뢰를 확인한 뒤에만 프로젝트 수준 서버를 불러오며, 신뢰하지 않는 디렉터리에서는 아무 알림 없이 건너뜁니다. Claude Code는 인터랙티브 세션에서 프로젝트 .mcp.json의 서버를 쓰기 전에 승인을 요청합니다.
• Android Studio의 httpUrl은 streamable HTTP 엔드포인트용이며, 문서는 SSE 엔드포인트에는 url을 쓰라고 합니다. Sume 빠른 시작은 streamable HTTP 서버를 요구하므로, Android Studio에서는 httpUrl을 쓰세요.