MCP Server

todoke supports the Model Context Protocol (MCP), allowing you to send Push notifications directly from AI agents like Claude.

Endpoint

https://api.todoke.dev/mcp

Served via Streamable HTTP transport. Authenticate with an Authorization: Bearer <API key> header; the key must have the notify or full scope (subscribe_only keys cannot call this endpoint).

Setup in Claude Code

Add the following to .mcp.json.

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

Available Tools

These are the 5 tools returned by tools/list. The target app is derived from the API key used for authentication — no app_id or api_key parameters are needed.

`send_notification`

Sends a Push notification to the subscribers of the current app (available with notify / full scope).

Parameter	Type	Required	Description
`title`	string	✅	Notification title
`body`	string	✅	Notification body
`url`	string	—	URL to open on click (`https://` only)
`endpoint`	string	—	If set, send only to this subscription endpoint

On success, returns { type: "text", text: 'Notification queued: "<title>"' }.

`get_stats`

Retrieves statistics for the current app (available with notify / full scope). Takes no parameters.

The response is JSON text with snake_case keys:

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

`list_api_keys`

Lists the API keys of the current app. Takes no parameters. Requires full scope.

`create_api_key`

Issues a new API key for the current app. Requires full scope.

Parameter	Type	Required	Description
`name`	string	✅	Label for the key
`scope`	string	—	`subscribe_only` / `notify` / `full`. Defaults to `notify`

The response contains the plaintext key (key). It is shown only in this response.

`delete_api_key`

Deletes the specified API key. Requires full scope.

Parameter	Type	Required	Description
`key_id`	string	✅	ID of the API key to delete

Scopes and the full Requirement

The three key-management tools (list_api_keys / create_api_key / delete_api_key) require a full-scope key. Calling them with a notify-scope key returns the following error without executing the tool:

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

send_notification / get_stats work with notify scope or higher (notify or full).

Error Behavior

When a tool call (tools/call) fails, the JSON-RPC response itself succeeds (has a result) with result.isError: true and the error message as text in content. The caller (AI agent) must check result.isError to determine success.