# 에디터·에이전트 연결

> Claude Code, Codex, Cursor, VS Code, Claude Desktop에 Specify MCP 서버를 등록하는 방법입니다.

워크스페이스의 **도구와 스킬** → **에디터 연결**에서 클라이언트를 선택하면, 해당 워크스페이스용 토큰이 발급되고 클라이언트별 명령이나 설정이 토큰이 채워진 상태로 준비됩니다. 이 페이지는 각 형식을 설명합니다.

<Screenshot name="tools-editor-connect" alt="도구와 스킬의 에디터 연결 탭. 새 연결의 권한, 문서 생성·수정 허용 체크박스, Claude Code·Cursor·VS Code·Claude Desktop·Codex 연결 카드가 보인다" caption="사이드바 계정 메뉴의 스킬 및 커넥터 → 에디터 연결 탭" />

## 연결 전에 권한 정하기

클라이언트 카드의 **연결**을 누르기 전에 **새 연결의 권한**을 확인하세요. 기본값은 **읽기 전용**으로, 문서 검색과 읽기만 허용합니다. 에이전트가 문서를 만들거나 고쳐야 한다면 **문서 생성·수정 허용**을 체크한 뒤 연결합니다. 이 설정은 이후 새로 발급하는 연결에 적용됩니다.

<Warning>
  토큰은 발급 화면에서만 표시됩니다. 분실했다면 새 토큰을 생성하세요. 토큰을 저장소, 공유 문서, 프롬프트에 붙여 넣지 마세요.
</Warning>

아래 예시의 `<SPECIFY_MCP_TOKEN>`은 발급받은 토큰으로 바꿔 넣습니다.

## 클라이언트별 연결

<Tabs>
  <Tab title="Claude Code">
    터미널에서 다음 명령을 실행합니다.

    ```bash
    claude mcp add specify --transport http https://mcp.specify.app \
      --header "Authorization: Bearer <SPECIFY_MCP_TOKEN>"
    ```

    등록 후 Claude Code에서 워크스페이스의 문서를 검색하고 읽을 수 있습니다. `claude mcp list`로 등록 상태를 확인할 수 있습니다.
  </Tab>
  <Tab title="Codex">
    `~/.codex/config.toml`에 다음 설정을 추가한 뒤 Codex를 다시 시작합니다. `url`이 있으면 Streamable HTTP 전송을 사용합니다.

    ```toml title="~/.codex/config.toml"
    [mcp_servers.specify]
    url = "https://mcp.specify.app"
    http_headers = { Authorization = "Bearer <SPECIFY_MCP_TOKEN>" }
    ```
  </Tab>
  <Tab title="Cursor">
    에디터 연결 화면에서 Cursor를 선택하면 설치 딥링크가 열려 Cursor에 서버가 등록됩니다. 열리지 않으면 표시된 링크를 복사해 붙여 넣으세요.

    직접 설정한다면 Cursor의 MCP 설정에 다음 항목을 추가합니다.

    ```json title="mcp.json"
    {
      "mcpServers": {
        "specify": {
          "url": "https://mcp.specify.app",
          "headers": { "Authorization": "Bearer <SPECIFY_MCP_TOKEN>" }
        }
      }
    }
    ```
  </Tab>
  <Tab title="VS Code">
    에디터 연결 화면에서 VS Code를 선택하면 `vscode:mcp/install` 딥링크로 서버 설치가 시작됩니다. 설치되는 설정은 다음과 같습니다.

    ```json
    {
      "name": "specify",
      "type": "http",
      "url": "https://mcp.specify.app",
      "headers": { "Authorization": "Bearer <SPECIFY_MCP_TOKEN>" }
    }
    ```
  </Tab>
  <Tab title="Claude Desktop">
    Claude Desktop의 설정 파일은 로컬(stdio) 서버만 받으므로, `mcp-remote` 프록시로 원격 서버에 연결합니다. 설정을 붙여 넣은 뒤 Claude Desktop을 다시 시작하세요.

    ```json title="claude_desktop_config.json"
    {
      "mcpServers": {
        "specify": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.specify.app", "--header", "Authorization:${AUTH_HEADER}"],
          "env": { "AUTH_HEADER": "Bearer <SPECIFY_MCP_TOKEN>" }
        }
      }
    }
    ```

    헤더 값은 `AUTH_HEADER` 환경 변수로 넘깁니다. 인자에 공백이 들어가지 않도록 `Authorization:` 뒤에 공백 없이 씁니다.

    <Warning>
      Claude Desktop 설정에 `type`, `url`, `headers` 형식의 원격 항목을 직접 넣지 마세요. Claude Desktop이 `mcpServers` 설정 전체를 지울 수 있습니다. 위와 같이 `mcp-remote`를 사용하세요.
    </Warning>
  </Tab>
</Tabs>

## OAuth로 연결하기

Specify MCP 서버는 OAuth 인가 코드 흐름(PKCE `S256`, 동적 클라이언트 등록)도 지원합니다. OAuth를 지원하는 클라이언트는 토큰 없이 서버 주소만 등록한 뒤, 브라우저에서 Specify에 로그인하고 워크스페이스와 권한 범위를 승인해 연결할 수 있습니다. 범위를 지정하지 않으면 읽기 전용으로 승인됩니다.

## 연결 확인

- 에이전트에게 "Specify에서 온보딩 문서를 찾아 줘"처럼 요청해 검색 도구가 호출되는지 확인합니다.
- **에디터 연결** 탭의 **에디터 접근 권한** 목록에서 발급된 권한과 마지막 사용 내역을 볼 수 있습니다. 이 목록은 실제 에디터 연결 상태와 다를 수 있습니다.

## 문제 해결

| 증상 | 확인할 점 |
| --- | --- |
| 인증 오류 | 토큰이 폐기되지 않았는지, `Bearer ` 접두사가 포함되었는지 확인합니다. |
| 도구 호출이 거부됨 | 워크스페이스 관리자가 외부 에디터 접근을 차단했거나 해당 작업을 허용하지 않았을 수 있습니다. [토큰과 접근 정책](/ko/mcp/access)을 참고하세요. |
| 문서 생성·수정이 안 됨 | 토큰에 쓰기 권한(`mcp:write`)이 없거나, 워크스페이스 역할이 편집자 미만입니다. |
| MCP 서버 URL이 설정되지 않았다고 표시됨 | 워크스페이스 관리자에게 문의하세요. |