> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# 트러블슈팅

> Tiro MCP Server의 자주 발생하는 문제와 해결법이에요.

MCP 설정 문제는 대부분 세 가지로 나뉘어요: auth 헤더, transport, 클라이언트 캐시. 순서대로 짚어보세요. 단계 사이에 클라이언트를 재시작해야 설정을 다시 읽어요.

## 연결 문제

### 서버를 찾을 수 없음

MCP 서버 URL이 맞는지 확인하세요: `https://mcp.tiro.ooo/mcp`

자주 하는 실수:

* `/mcp` 경로 suffix 누락
* `https://` 대신 `http://` 사용

연결 테스트:

```bash theme={"system"}
curl https://mcp.tiro.ooo/mcp
```

예상 응답: `405 Method Not Allowed` (GET 요청에선 정상이에요).

### 도구가 안 보임

1. MCP 클라이언트를 완전히 재시작하세요(창 새로고침 말고)
2. AI에게 "List all available MCP servers"라고 물어 Tiro가 나오는지 확인하세요
3. 그래도 없으면 [클라이언트 설정](/ko/developers/mcp/setup)을 다시 진행하세요

## 인증 에러

### API Key 문제

**잘못된 API Key 형식**

API Key는 `{id}.{secret}` 형식(점으로 구분된 두 부분)을 따라야 해요. 자주 하는 실수:

* key의 일부만 복사(점 앞이나 뒤 부분 누락)
* key에 공백이나 줄바꿈 문자가 섞임
* 실제 key 대신 placeholder 값 사용

```bash theme={"system"}
# Correct format
TIRO_API_KEY=abc123.xyz789secretvalue

# Wrong — missing the dot separator
TIRO_API_KEY=abc123xyz789secretvalue
```

**만료되거나 폐기된 Key**

API Key는 Tiro Dashboard에서 만료되거나 폐기될 수 있어요. 이전에 쓰던 API key로 `401 UNAUTHORIZED` 에러가 나면:

1. [Tiro Platform API Keys](https://platform.tiro.ooo/dashboard/api-keys)로 가세요
2. key가 아직 활성인지 확인하고, 필요하면 새로 발급하세요
3. MCP 클라이언트 설정을 새 key로 업데이트하세요

### 401 Unauthorized / 403 Forbidden

**API Key 사용 시:** key가 유효하고 만료되지 않았으며 호출하려는 도구에 필요한 scope를 가졌는지 확인하세요. 전체 scope 표는 [Setup 페이지](/ko/developers/mcp/setup)를 보세요.

**OAuth 사용 시:** MCP 클라이언트를 재시작해 새 OAuth 흐름을 트리거하세요.

* **Claude Code**: CLI 세션 재시작
* **Claude Desktop**: 앱을 완전히 종료 후 재실행
* **Cursor**: 에디터 재시작 또는 MCP extension 리로드
* **VS Code**: 에디터 재시작 또는 MCP extension 리로드

OAuth는 올바른 scope로 새 token을 자동 발급해요. token은 **180일** 동안 유효해요.

## 설정 문제

### Claude Code 연결 실패

1. 설정이 [Claude Code setup](/ko/developers/mcp/setup)과 맞는지 확인하세요
2. CLI 세션을 재시작하세요
3. OAuth를 쓰는데 브라우저 창이 안 열리면 기본 브라우저 설정을 확인하세요
4. API Key를 쓴다면 key 값에 끝 공백이 없는지 확인하세요

### Claude Desktop 연결 실패

1. 설정이 [Claude Desktop setup](/ko/developers/mcp/setup)과 맞는지 확인하세요
2. JSON 문법을 검증하세요 — 누락된 쉼표, 안 맞는 괄호, 누락된 따옴표 확인([JSONLint](https://jsonlint.com/))
3. [Node.js](https://nodejs.org/)가 설치돼 있는지 확인하세요(터미널에서 `npx`가 동작해야 함)
4. Claude Desktop을 완전히 종료 후 재시작하세요(macOS는 Cmd+Q, 창만 닫지 말고)

### Cursor 연결 실패

1. Cursor 설정에서 MCP 서버 설정을 확인하세요
2. 서버 URL이 `https://mcp.tiro.ooo/mcp`인지 확인하세요
3. API Key를 쓴다면 설정에 올바르게 들어갔는지 확인하세요(따옴표·공백 없이)
4. Cursor를 완전히 재시작하고 MCP 패널에서 연결 상태를 확인하세요

### VS Code 연결 실패

1. MCP extension 설정을 확인하세요(예: Continue 설정 또는 Copilot MCP config)
2. 서버 URL이 `https://mcp.tiro.ooo/mcp`인지 확인하세요
3. API Key를 쓴다면 올바른 config 필드에 들어갔는지 확인하세요
4. VS Code 창을 리로드하고(`Cmd+Shift+P` → "Reload Window") extension 로그에서 에러를 확인하세요

## 검색 & 데이터 문제

* **결과가 없나요?** 더 넓은 검색 조건을 써보세요 — `content`에 일반 키워드 하나만 쓰거나 `createdAt` 날짜 범위를 넓히세요
* **날짜 형식 에러?** timezone 포함 ISO 8601을 쓰세요: `2025-11-22T00:00:00Z` (날짜만 있는 형식은 안 돼요)
* **최근 노트가 안 보이나요?** 캐싱 때문에 노트가 나타나기까지 최대 15분 걸릴 수 있어요. [Tiro Dashboard](https://tiro.ooo)에서 노트가 "Completed"인지 확인하세요
* **요청 timeout?** 긴 회의에는 `get_note_transcript` 대신 `get_note(include: ['summary'])`를 쓰세요

## 에러 레퍼런스

| Code                    | HTTP | 설명                                 | 해결                                                                       |
| ----------------------- | ---- | ---------------------------------- | ------------------------------------------------------------------------ |
| `UNAUTHORIZED`          | 401  | 유효한 인증 없음                          | API key 확인 또는 클라이언트 재시작해 OAuth 재인증                                       |
| `TOKEN_EXPIRED`         | 401  | token 만료됨                          | 새 API key 발급 또는 클라이언트 재시작해 OAuth 재인증                                     |
| `FORBIDDEN`             | 403  | 필요한 scope 없음                       | API key scope 확인 또는 클라이언트 재시작해 OAuth 재인증                                 |
| `INSUFFICIENT_SCOPE`    | 403  | 인증된 key/token에 이 도구에 필요한 scope가 없음 | [Setup 페이지](/ko/developers/mcp/setup)의 scope 표를 확인하고 올바른 scope의 key를 쓰세요 |
| `MISSING_PARAMETERS`    | 400  | 필수 param 누락                        | param 요건 확인                                                              |
| `INVALID_NOTE_ID`       | 400  | 잘못된 note ID                        | 양의 정수 사용                                                                 |
| `INVALID_DATE_FORMAT`   | 400  | 잘못된 날짜 형식                          | ISO 8601 datetime 사용                                                     |
| `NOTE_NOT_FOUND`        | 404  | 노트가 없음                             | note ID 확인                                                               |
| `INTERNAL_SERVER_ERROR` | 500  | 서버 에러                              | 재시도 또는 지원 문의                                                             |
| `REQUEST_TIMEOUT`       | 504  | 요청 timeout                         | summary 사용 또는 재시도                                                        |

## 도움 받기

[GitHub](https://github.com/plato-corp/tiro-mcp-server/issues)에 이슈를 열거나 [support@tiro.ooo](mailto:support@tiro.ooo)로 메일 주세요.