Specify MCP
Claude Code, Codex, Cursor, VS Code, Claude Desktop에 Specify MCP 서버를 등록하는 방법입니다.
워크스페이스의 도구와 스킬 → 에디터 연결에서 클라이언트를 선택하면, 해당 워크스페이스용 토큰이 발급되고 클라이언트별 명령이나 설정이 토큰이 채워진 상태로 준비됩니다. 이 페이지는 각 형식을 설명합니다.
연결 전에 권한 정하기
클라이언트 카드의 연결을 누르기 전에 새 연결의 권한을 확인하세요. 기본값은 읽기 전용으로, 문서 검색과 읽기만 허용합니다. 에이전트가 문서를 만들거나 고쳐야 한다면 문서 생성·수정 허용을 체크한 뒤 연결합니다. 이 설정은 이후 새로 발급하는 연결에 적용됩니다.
토큰은 발급 화면에서만 표시됩니다. 분실했다면 새 토큰을 생성하세요. 토큰을 저장소, 공유 문서, 프롬프트에 붙여 넣지 마세요.
아래 예시의 <SPECIFY_MCP_TOKEN>은 발급받은 토큰으로 바꿔 넣습니다.
클라이언트별 연결
터미널에서 다음 명령을 실행합니다.
claude mcp add specify --transport http https://mcp.specify.app \
--header "Authorization: Bearer <SPECIFY_MCP_TOKEN>"등록 후 Claude Code에서 워크스페이스의 문서를 검색하고 읽을 수 있습니다. claude mcp list로 등록 상태를 확인할 수 있습니다.
~/.codex/config.toml에 다음 설정을 추가한 뒤 Codex를 다시 시작합니다. url이 있으면 Streamable HTTP 전송을 사용합니다.
[mcp_servers.specify]
url = "https://mcp.specify.app"
http_headers = { Authorization = "Bearer <SPECIFY_MCP_TOKEN>" }에디터 연결 화면에서 Cursor를 선택하면 설치 딥링크가 열려 Cursor에 서버가 등록됩니다. 열리지 않으면 표시된 링크를 복사해 붙여 넣으세요.
직접 설정한다면 Cursor의 MCP 설정에 다음 항목을 추가합니다.
{
"mcpServers": {
"specify": {
"url": "https://mcp.specify.app",
"headers": { "Authorization": "Bearer <SPECIFY_MCP_TOKEN>" }
}
}
}에디터 연결 화면에서 VS Code를 선택하면 vscode:mcp/install 딥링크로 서버 설치가 시작됩니다. 설치되는 설정은 다음과 같습니다.
{
"name": "specify",
"type": "http",
"url": "https://mcp.specify.app",
"headers": { "Authorization": "Bearer <SPECIFY_MCP_TOKEN>" }
}Claude Desktop의 설정 파일은 로컬(stdio) 서버만 받으므로, mcp-remote 프록시로 원격 서버에 연결합니다. 설정을 붙여 넣은 뒤 Claude Desktop을 다시 시작하세요.
{
"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: 뒤에 공백 없이 씁니다.
Claude Desktop 설정에 type, url, headers 형식의 원격 항목을 직접 넣지 마세요. Claude Desktop이 mcpServers 설정 전체를 지울 수 있습니다. 위와 같이 mcp-remote를 사용하세요.
OAuth로 연결하기
Specify MCP 서버는 OAuth 인가 코드 흐름(PKCE S256, 동적 클라이언트 등록)도 지원합니다. OAuth를 지원하는 클라이언트는 토큰 없이 서버 주소만 등록한 뒤, 브라우저에서 Specify에 로그인하고 워크스페이스와 권한 범위를 승인해 연결할 수 있습니다. 범위를 지정하지 않으면 읽기 전용으로 승인됩니다.
연결 확인
- 에이전트에게 "Specify에서 온보딩 문서를 찾아 줘"처럼 요청해 검색 도구가 호출되는지 확인합니다.
- 에디터 연결 탭의 에디터 접근 권한 목록에서 발급된 권한과 마지막 사용 내역을 볼 수 있습니다. 이 목록은 실제 에디터 연결 상태와 다를 수 있습니다.
문제 해결
| 증상 | 확인할 점 |
|---|---|
| 인증 오류 | 토큰이 폐기되지 않았는지, Bearer 접두사가 포함되었는지 확인합니다. |
| 도구 호출이 거부됨 | 워크스페이스 관리자가 외부 에디터 접근을 차단했거나 해당 작업을 허용하지 않았을 수 있습니다. 토큰과 접근 정책을 참고하세요. |
| 문서 생성·수정이 안 됨 | 토큰에 쓰기 권한(mcp:write)이 없거나, 워크스페이스 역할이 편집자 미만입니다. |
| MCP 서버 URL이 설정되지 않았다고 표시됨 | 워크스페이스 관리자에게 문의하세요. |