MCP server

The app serves a stateless Streamable HTTP MCP server from /api/mcp. Point an MCP client at the complete app URL, for example:

https://your-app.example/api/mcp

The same endpoint supports public and protected tools. Clients can initialize the connection and discover every tool without signing in.

Public Todo tools

Todo tools share one public collection across every caller. They require no authentication or authorization. The collection holds at most 1,000 records; list_todos accepts filter, orderBy, pageSize, and pageToken, and returns todos with nextPageToken. Omitted or zero page sizes default to 50; values above 1,000 are capped at 1,000. Filters use AIP expressions, such as NOT completed AND title = "*read*"; an empty filter includes every Todo. Resources retain their canonical path field.

• list_todos
• create_todo
• toggle_todo
• delete_todo
• clear_completed_todos

Call toggle_todo with a Todo path. Omit completed to invert the current state, or provide it to set an exact state.

Organization and Project tools

Organization and Project tools use OAuth 2.0 authorization code flow with PKCE. The server supports dynamic client registration. MCP clients discover the authorization server through the protected-resource metadata published at /.well-known/oauth-protected-resource/api/mcp.

Request the mcp scope to call:

• list_organizations
• get_organization
• list_projects: accepts the same list controls plus parent; for example, filter: "dueAt != null".
• get_project
• create_project
• update_project
• delete_project

Project tools use resource path or parent fields whose segments accept either stable IDs or slugs. Project reads require Organization membership. Existing Organization roles remain authoritative: Owners and Admins can create and update Projects, while only Owners can delete them.

Clients may additionally request the standard offline_access scope when they need a refresh token.

Results and errors

Successful tools return equivalent structured JSON and text JSON. Expected failures return a safe error code and message, such as NOT_FOUND, PERMISSION_DENIED, or RESOURCE_EXHAUSTED. Calling a protected tool without OAuth credentials returns an UNAUTHENTICATED tool error.