Docs
/
Menu

DocsFor developers

Leaf's MCP server

The technical details of connecting an agent: transport, OAuth, tokens, conventions.

Endpoint

https://mcp.getleaf.dev/mcp

Streamable HTTP, stateless: each request is bound to the person its token names, so rights are read on every call.

Authorization

  • OAuth 2.1 with PKCE (S256) and dynamic client registration. /mcp answers 401 pointing to its protected resource metadata (RFC 9728), which names the issuer https://app.getleaf.dev/v1/auth.
  • Clients that register only http://localhost callbacks (Claude Code, Cursor) are treated as native apps (RFC 8252), on any port.
  • One grant per person covers all their organisations; a call finds its organisation from what it names (project--organisation, a draft, or org).
  • Access tokens are JWTs for the resource https://mcp.getleaf.dev/mcp. A new password revokes every grant; Your AI revokes one.

Conventions

  • Tools are named <noun>_<verb>; lists end in _list; _patch always changes something; reading is always its own tool.
  • Every tool carries a title and readOnlyHint / destructiveHint. See Leaf's tools.
  • Writes are all or nothing and carry the revision or updatedAt read: a stale one is refused, never overwritten.
  • Refusals come as Refused (code): message with a hint.
  • Changes made through an agent carry the person as author and the agent as committer ("Ada via Claude").