# 내 AI 연결하기 (MCP 설치)

> Claude Code·Cursor 같은 내 AI 코딩 도구에 Specnote를 연결하는 방법을 도구별로 정리했어요. 한 번만 해 두면, 그 다음부터는 "이거 테스트 만들어 줘"라고 말하는 것으로 충분합니다.

## 왜 연결하나요

Specnote에서 **테스트를 만드는 일은 내 AI가 대신**해요. 그래서 Cursor·Claude Code처럼 평소 쓰는 AI 코딩 도구를 Specnote에 한 번 연결해 두어야 합니다. 연결하고 나면 그 도구 안에서 "회원가입 테스트 만들어 줘"라고 말하는 것만으로 테스트가 만들어져요.

이때 쓰는 표준 통로가 **MCP**(Model Context Protocol)예요. AI 도구가 외부 서비스와 안전하게 대화하도록 약속된 통로라고 보시면 됩니다. 어렵게 들리지만, 실제로 하실 일은 아래 안내대로 명령 한두 줄을 붙여넣는 게 전부예요.

연결 주소는 도구가 무엇이든 하나로 같아요.

```
https://specnote.io/api/mcp/mcp
```

## Claude Code — 방법 1. 플러그인 (권장)

Claude Code를 쓰신다면 플러그인으로 설치하는 게 가장 쉬워요. Claude Code 안에서 아래 두 줄을 차례로 입력합니다.

```
/plugin marketplace add Dannect/specnote-mcp
/plugin install specnote@specnote-mcp
```

설치가 끝나면 `/mcp`를 입력해 specnote를 고르세요. 브라우저가 열리면서 "허용" 버튼이 나오는데, 한 번 누르면 인증이 끝나요. 토큰을 복사하거나 다룰 필요가 전혀 없고, 한 번 허용해 두면 30일 동안 자동으로 안전하게 갱신됩니다.

## Claude Code — 방법 2. 명령 한 줄

플러그인 대신 명령 한 줄로 붙일 수도 있어요. 터미널에서 아래를 입력합니다.

```
claude mcp add --transport http specnote https://specnote.io/api/mcp/mcp
```

이렇게 하면 처음 쓸 때 브라우저 인증("허용" 한 번)을 거쳐요. 자동 환경처럼 브라우저를 열 수 없는 곳이라면, 아래에서 설명할 **연결 토큰**을 발급받아 이렇게 붙입니다.

```
claude mcp add --transport http specnote https://specnote.io/api/mcp/mcp --header "Authorization: Bearer <내 연결 토큰>"
```

## Cursor에 연결하기

Cursor는 설정 파일에 Specnote를 적어 주면 돼요. 먼저 아래 "연결 토큰 발급"에서 토큰을 받아 두세요. 그다음 Cursor 설정에서 **MCP** 메뉴를 열고(Settings → MCP → Add new global MCP server), 아래 내용을 붙여넣습니다.

```json
{
  "mcpServers": {
    "specnote": {
      "url": "https://specnote.io/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer <내 연결 토큰>"
      }
    }
  }
}
```

`<내 연결 토큰>` 자리에 발급받은 토큰을 그대로 넣으면 돼요. 저장하면 Cursor가 Specnote와 연결됩니다.

## 그 외 MCP를 지원하는 도구

Windsurf, Codex 등 MCP를 지원하는 도구라면 무엇이든 같은 방식으로 연결할 수 있어요. 도구의 MCP 서버 추가 화면에서 두 가지만 넣으면 됩니다.

- **주소**: `https://specnote.io/api/mcp/mcp` (방식은 HTTP)
- **인증 헤더**: `Authorization: Bearer <내 연결 토큰>`

도구마다 화면 이름은 조금씩 달라도, 이 두 값만 들어가면 연결돼요.

## 연결 토큰 발급받기

토큰이 필요한 방식(Cursor·자동 환경 등)을 쓰신다면, [마이페이지](https://specnote.io/ko/mypage)의 **MCP 연결**에서 발급받으세요. 버튼 한 번이면 `spnt_`로 시작하는 토큰이 만들어져요.

이 토큰은 **비밀번호처럼** 다뤄 주세요. 깃(git)에 올리거나 남에게 공유하지 말고, 새어 나간 것 같으면 마이페이지에서 즉시 폐기하고 새로 발급받으면 됩니다. 토큰은 따로 만료되지 않아서, 직접 폐기하기 전까지 계속 쓸 수 있어요.

## 연결됐는지 확인하기

연결이 끝났다면, AI에게 이렇게 말해 보세요.

> 내 Specnote 워크스페이스 목록 보여 줘.

만들어 둔 워크스페이스 이름이 답으로 돌아오면 성공이에요. 아직 워크스페이스가 없다면 "Specnote에 '우리 쇼핑몰' 워크스페이스 만들어 줘"라고 바로 부탁해도 됩니다.

연결 후 무엇을 시킬 수 있는지 한눈에 보려면 [AI에게 시킬 수 있는 일 모음](/ko/docs/mcp-tools)을 봐 주세요.

## 잘 안 될 때

- **`/mcp`에 specnote가 안 보여요.** 플러그인 설치 두 줄이 모두 끝났는지 확인하고, Claude Code를 한 번 재시작해 보세요.
- **브라우저 인증 창이 안 떠요.** `/mcp`에서 specnote를 골라 인증을 다시 시도해 보세요. 그래도 안 되면 토큰 방식으로 바꿔 연결하는 게 빠릅니다.
- **"인증 실패"라고 나와요.** 토큰이 마이페이지에서 폐기되지 않았는지 확인하고, 필요하면 새로 발급받아 설정의 토큰 값을 바꿔 주세요.

더 많은 증상별 해결법은 [문제 해결](/ko/docs/troubleshooting)에 모아 두었어요. 연결을 마쳤다면 [5분 만에 첫 검증 받기](/ko/docs/quickstart)로 이어서 첫 테스트를 만들어 보세요.

---

Source: https://specnote.io/ko/docs/install-mcp