> ## 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 のセットアップに関する問題のほとんどは、3 つのカテゴリーに分類されます。auth ヘッダー、transport、そしてクライアントのキャッシュです。これらを順番に確認してください。各ステップの間にクライアントを再起動すると、設定が確実に読み込み直されます。

## 接続の問題

### Server Not Found

MCP server の URL が正しいか確認してください：`https://mcp.tiro.ooo/mcp`

よくある間違い：

* `/mcp` のパス末尾が欠けている
* `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. それでも表示されない場合は、[client setup](/ja/developers/mcp/setup) をやり直す

## 認証エラー

### API Key の問題

**API Key の形式が無効**

API Key は `{id}.{secret}` の形式（ドットで区切られた 2 つの部分）に従う必要があります。よくある間違い：

* key の一部だけをコピーしている（ドットの前または後の部分が欠けている）
* key に余分な空白や改行文字が含まれている
* 実際の key ではなくプレースホルダーの値を使っている

```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 がまだ有効か確認する。必要であれば新しい key を生成する
3. MCP クライアントの設定を新しい key で更新する

### 401 Unauthorized / 403 Forbidden

**API Key を使う場合：** key が有効で、期限切れでなく、呼び出すツールに必要な scope を持っているか確認してください。すべての scope の表については [Setup page](/ja/developers/mcp/setup) をご覧ください。

**OAuth を使う場合：** MCP クライアントを再起動して、新しい OAuth フローを起動してください。

* **Claude Code**：CLI セッションを再起動する
* **Claude Desktop**：アプリを完全に終了して再起動する
* **Cursor**：エディタを再起動するか、MCP 拡張機能を再読み込みする
* **VS Code**：エディタを再起動するか、MCP 拡張機能を再読み込みする

OAuth は、正しい scope を持つ新しい token を自動的に発行します。token は **180 日間**有効です。

## 設定の問題

### Claude Code が接続できない

1. 設定が [Claude Code setup](/ja/developers/mcp/setup) と一致しているか確認する
2. CLI セッションを再起動する
3. OAuth を使っていてブラウザウィンドウが開かない場合は、デフォルトのブラウザ設定を確認する
4. API Key を使っている場合は、key の値に末尾の空白がないか確認する

### Claude Desktop が接続できない

1. 設定が [Claude Desktop setup](/ja/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 server の設定を確認する
2. server URL が `https://mcp.tiro.ooo/mcp` であることを確認する
3. API Key を使っている場合は、設定に正しく入力されているか確認する（余分な引用符や空白がないこと）
4. Cursor を完全に再起動し、MCP パネルで接続状態を確認する

### VS Code が接続できない

1. MCP 拡張機能の設定（例：Continue の設定や Copilot MCP の設定）を確認する
2. server URL が `https://mcp.tiro.ooo/mcp` であることを確認する
3. API Key を使っている場合は、正しい設定フィールドに入力されているか確認する
4. VS Code のウィンドウを再読み込みし（`Cmd+Shift+P` → 「Reload Window」）、拡張機能のログにエラーがないか確認する

## 検索とデータの問題

* **結果が出ない？** より広い検索条件を試してください。`content` に一般的なキーワードを 1 つだけ使うか、`createdAt` の日付範囲を広げてください
* **日付形式のエラー？** タイムゾーン付きの ISO 8601 を使ってください：`2025-11-22T00:00:00Z`（日付のみの形式は受け付けられません）
* **最近のノートが見つからない？** キャッシュのため、ノートが表示されるまで最大 15 分かかることがあります。ノートが [Tiro Dashboard](https://tiro.ooo) で「Completed」になっているか確認してください
* **リクエストがタイムアウトする？** 長い会議では、`get_note_transcript` の代わりに `get_note(include: ['summary'])` を使ってください

## エラーリファレンス

| Code                    | HTTP | Description                           | Solution                                                                   |
| ----------------------- | ---- | ------------------------------------- | -------------------------------------------------------------------------- |
| `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 page](/ja/developers/mcp/setup) の scope 表を確認し、正しい scope を持つ key を使う |
| `MISSING_PARAMETERS`    | 400  | 必須パラメータが欠けている                         | パラメータの要件を確認する                                                              |
| `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  | リクエストがタイムアウトした                        | 要約を使うか、再試行する                                                               |

## サポート

[GitHub](https://github.com/plato-corp/tiro-mcp-server/issues) で issue を作成するか、[support@tiro.ooo](mailto:support@tiro.ooo) までメールでご連絡ください。