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 toolsCopy Anchor Link

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, pageToken, and skip, and returns todos, nextPageToken, and the filtered totalSize. Omitted or zero page sizes default to 10; 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

An empty nextPageToken marks the final page. skip is a nonnegative offset from the current page-token position.

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 toolsCopy Anchor Link

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: "dueTime:*".
• get_project
• create_project
• update_project
• delete_project

Project tools use resource path or parent fields whose segments accept stable IDs or slugs. For list_projects, specify parent, such as organizations/acme, to read one Organization. Omitting it defaults to organizations/-, a cross-Organization list requiring app-admin access. List responses include projects, nextPageToken, and the filtered totalSize.

Project reads within one Organization require membership. Owners and Admins can create and update Projects; only Owners can delete them.

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

Results and errorsCopy Anchor Link

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.