개발자 문서
개발자 문서

AI 에디터 · 앱 연동

Claude · Cursor · VS Code · Windsurf · Continue · Zed · Codex 에 XBOSS MCP 를 붙이는 설정입니다.

앱에 따라 설정 방법이 다릅니다.

설정 파일에 주소와 헤더를 적는 방식 — Cursor · VS Code · Windsurf · Continue · Zed · Claude Code.

명령 한 줄로 등록하는 방식 — Claude Code CLI.

중계 프로그램을 쓰는 방식 — Claude Desktop(npx mcp-remote).

앱의 커넥터 화면에서 직접 추가하는 방식 — Claude Desktop 일부 버전에서 선택할 수 있습니다.

앱별 설정 파일

앱설정 파일
Claude Desktop먼저 Claude Desktop의 설정 → 개발자 → 구성 편집에서 실제 설정 파일 위치를 확인합니다. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %LOCALAPPDATA%\Claude-Data\claude_pzs8sxrjxfjjc\claude_desktop_config.json (이전 버전은 %APPDATA%\Claude\claude_desktop_config.json 또는 %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json)
Claude Code프로젝트 루트 .mcp.json
Cursor~/.cursor/mcp.json 또는 프로젝트 .cursor/mcp.json
VS Code프로젝트 .vscode/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
Continue작업 폴더의 .continue/mcpServers/xboss.yaml
ZedmacOS·Linux ~/.config/zed/settings.json · Windows %APPDATA%\Zed\settings.json
Codex · ChatGPT 데스크톱~/.codex/config.toml

아래 설정의 Basic <base64(client_id:client_secret)> 자리에는 실제 값을 넣습니다.

환경 헤더(X-MCP-Env-Scope)를 넣지 않으면 자격증명이 환경을 정합니다.

그래서 정식 환경 설정에는 환경 헤더가 없고, 데모 환경 설정에는 X-MCP-Env-Scope: real_test 가 함께 들어 있습니다.

Claude Desktop

claude_desktop_config.json
json
{
  "mcpServers": {
    "xboss": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.xdata.kr/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

설정 파일을 저장했다면 Claude Desktop을 완전히 종료했다가 다시 켭니다.

일부 앱 버전에서는 설정 > 커넥터 > 추가 > 커스텀 커넥터 추가로 직접 연결할 수 있습니다.

요청 헤더 칸이 없으면 위 설정 파일 방식을 사용합니다.

Claude Code — 명령 한 줄

terminal
bash
claude mcp add --transport http xboss https://api.xdata.kr/mcp --header "Authorization: Basic <base64(client_id:client_secret)>"

Claude Code — 프로젝트 설정 파일

.mcp.json
json
{
  "mcpServers": {
    "xboss": {
      "type": "http",
      "url": "https://api.xdata.kr/mcp",
      "headers": {
        "Authorization": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

.mcp.json 은 프로젝트를 함께 쓰는 사람 모두에게 적용됩니다.

루트 키는 mcpServers 이고 각 서버에 "type": "http" 가 필요합니다(VS Code 의 servers 와 다릅니다).

Cursor

mcp.json
json
{
  "mcpServers": {
    "xboss": {
      "url": "https://api.xdata.kr/mcp",
      "headers": {
        "Authorization": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

VS Code

.vscode/mcp.json
json
{
  "servers": {
    "xboss": {
      "type": "http",
      "url": "https://api.xdata.kr/mcp",
      "headers": {
        "Authorization": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

Windsurf

mcp_config.json
json
{
  "mcpServers": {
    "xboss": {
      "serverUrl": "https://api.xdata.kr/mcp",
      "headers": {
        "Authorization": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

Windsurf 는 원격 서버 주소를 url 이 아니라 serverUrl 로 적습니다.

Continue

xboss.yaml
yaml
name: xboss
version: 0.0.1
schema: v1
mcpServers:
  - name: xboss
    type: streamable-http
    url: https://api.xdata.kr/mcp
    requestOptions:
      headers:
        Authorization: "Basic <base64(client_id:client_secret)>"

Zed

settings.json
json
{
  "context_servers": {
    "xboss": {
      "url": "https://api.xdata.kr/mcp",
      "headers": {
        "Authorization": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

Zed 설정은 context_servers 아래에 넣습니다. 기존 설정 파일에 이 부분만 합칩니다.

Codex · ChatGPT 데스크톱

config.toml
toml
[mcp_servers.xboss]
url = "https://api.xdata.kr/mcp"
http_headers = { Authorization = "Basic <base64(client_id:client_secret)>" }

ChatGPT 데스크톱 앱은 Codex 와 같은 config.toml 을 씁니다. ChatGPT 웹 커넥터 연결은 콘솔 MCP 안내를 따릅니다.

연결이 안 될 때

앱을 다시 켠 뒤에도 도구가 보이지 않으면 연결 확인 명령을 터미널에서 실행해 봅니다. 명령은 MCP 개요에 있고, 같은 설정 값을 씁니다.

  • 도구 목록이 오면 설정 파일 위치나 형식 문제입니다.
  • 오류가 오면 MCP 오류 코드에서 코드를 찾습니다.