MCP サーバー

todoke は Model Context Protocol (MCP) に対応しており、Claude などの AI エージェントから直接 Push 通知の送信や統計取得、API キー管理ができます。

エンドポイント

https://api.todoke.dev/mcp

Streamable HTTP トランスポートで提供します。認証は Authorization: Bearer <APIキー> ヘッダーで行い、キーには notify または full スコープが必要です（subscribe_only キーではエンドポイント自体を呼び出せません）。プロトコルバージョンは 2024-11-05 です。

接続例

Claude Code

プロジェクトの .mcp.json、またはユーザー設定に以下を追加します。

{
  "mcpServers": {
    "todoke": {
      "type": "http",
      "url": "https://api.todoke.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_your_notify_or_full_key"
      }
    }
  }
}

設定後、Claude Code の /mcp コマンドでサーバーが認識されていることを確認できます。

claude.ai などその他の MCP クライアント

Streamable HTTP に対応した MCP クライアントであれば同様に接続できます。接続 URL（https://api.todoke.dev/mcp）と Authorization: Bearer <APIキー> ヘッダーを、お使いのクライアントの MCP サーバー追加 UI・設定ファイルに設定してください。具体的な設定手順はクライアントごとに異なるため、それぞれの公式ドキュメントを参照してください。

利用可能なツール

tools/list で取得できる 5 つのツールです。

`send_notification`

指定したアプリの購読者に Push 通知を送信します（notify / full スコープで利用可）。

引数	型	必須	説明
`title`	string	✅	通知タイトル
`body`	string	✅	通知本文
`url`	string	—	クリック時の遷移先（`https://` のみ）
`endpoint`	string	—	指定時は特定の購読エンドポイントのみに送信

成功時は { type: "text", text: 'Notification queued: "<title>"' } を返します。

`get_stats`

現在のアプリの統計を取得します（notify / full スコープで利用可）。引数はありません。

レスポンスは snake_case の JSON テキストです。

{
  "active_subscribers": 42,
  "total_sent": 1234,
  "total_failed": 3,
  "monthly_sent": 567
}

`list_api_keys`

現在のアプリの API キー一覧を取得します。引数はありません。full スコープ必須です。

`create_api_key`

現在のアプリに新しい API キーを発行します。full スコープ必須です。

引数	型	必須	説明
`name`	string	✅	キーのラベル
`scope`	string	—	`subscribe_only` / `notify` / `full`。省略時は `notify`

レスポンスに発行された平文キー（key）が含まれます。表示されるのはこの応答のみです。

`delete_api_key`

指定した API キーを削除します。full スコープ必須です。

引数	型	必須	説明
`key_id`	string	✅	削除する API キーの ID

スコープと full 要件

list_api_keys / create_api_key / delete_api_key の 3 ツールは API キー自体を管理するため、full スコープのキーでの呼び出しが必須です。notify スコープのキーでこれらを呼び出すと、ツールは実行されずに次のエラーが返ります。

{
  "content": [{ "type": "text", "text": "Error: This tool requires full scope" }],
  "isError": true
}

send_notification / get_stats は notify スコープ以上（notify または full）で呼び出せます。

エラー時の挙動

MCP のツール呼び出し（tools/call）でエラーが発生した場合、JSON-RPC 自体は成功（result あり）として返り、result.isError: true とともにエラー内容が content に文字列で入ります。主なメッセージは次のとおりです。

状況	メッセージ
full スコープが必要なツールを notify キーで呼んだ	`Error: This tool requires full scope`
月間送信上限（Free: 30,000通）を超過	`Error: Monthly limit exceeded`
送信ペイロードが上限（3,072 バイト）を超過	`Error: Payload too large`
`url` が `https://` でない	`Error: url must be an https:// URL`
削除対象の API キーが存在しない	`Error: API key not found`
ツール実行中に予期しない例外が発生	`Error: Tool execution failed`