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	—	指定時は特定の購読エンドポイントのみに送信
`dry_run`	boolean	—	`true` の場合は検証と送信見込み件数の取得だけを行う

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

実送信の前に dry_run: true で呼び出し、送信先件数を確認してください。実送信と同じ検証を行いますが Queue には投入せず、Dry run: would send to N subscriber(s). Nothing was queued. を返します。endpoint を指定した場合は、API キーに紐づく同じアプリの有効購読だけを数えます。

`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`
引数を使うツールの `arguments` がオブジェクトでない	`Error: arguments must be an object`
`title` または `body` が未指定・空文字列・文字列以外	`Error: title and body are required`
`dry_run` が boolean でない	`Error: dry_run must be a boolean`
月間送信上限（Free: 30,000通）を超過	`Error: Monthly limit exceeded`
送信ペイロードが上限（3,072 バイト）を超過	`Error: Payload too large`
`url` が truthy で、文字列でないか `https://` の URL でない	`Error: url must be an https:// URL`
`endpoint` が truthy で、文字列でないか許可されない送信先	`Error: Invalid endpoint`
`name` が文字列でないか、前後の空白を除くと空	`Error: name is required`
`scope` が `subscribe_only` / `notify` / `full` 以外（`null` も不可）	`Error: Invalid scope (expected subscribe_only, notify, or full)`
`key_id` が文字列でないか、前後の空白を除くと空	`Error: key_id is required`
削除対象の API キーが存在しない	`Error: API key not found`
サーバ側の予期しない異常（入力の誤りでは返らない）	`Error: Tool execution failed`