Quater Manual

This manual explains how Quater helps you build Python backends that people can use through normal APIs and AI agents can operate through explicit tools and actions.

Prerequisites

You should know async Python, HTTP handlers, and basic type annotations. You do not need prior MCP knowledge; the MCP guide starts with the protocol model.

The Short Version

Quater is for backends that need to serve people and services through normal APIs, while also exposing selected views directly to AI agents and MCP clients.

You declare a route, then opt it into the surfaces you want:

• HTTP by declaring the route.
• MCP by adding tool=True.
• CLI by adding cli=True.

That keeps application logic in one place instead of spreading it across API routes, tool wrappers, scripts, and internal-only shortcuts.

Direct backend access does not mean broad backend access. Quater keeps each surface behind its own boundary: mcp_auth protects MCP, cli_auth protects CLI, and route auth= protects the handler itself.

Read Why Quater Exists for the full problem statement and design motivation.

Non-goals

Quater does not ship an ORM, a template engine, a background worker, or a user account system. It does not try to recreate Django/FastAPI/Flask. It also does not expose every Starlette or ASGI primitive directly; ASGI and WSGI exist for compatibility.

Who It Is For

Use Quater when you build API services where humans, agents, and MCP clients need controlled access to the same backend operations. It fits teams that care about typed handlers, generated schemas, explicit auth, AI-readable metadata, operational safety, and low request overhead.

How The Docs Are Organized

The docs are split by how a developer learns the framework:

• Quickstart gets a working app running.
• Why Quater Exists explains the problem behind the framework.
• Core concepts explain routes, surfaces, auth, resources, and middleware.
• Guides cover MCP, Actions and CLI, Testing, Deployment, and Security.
• Reference gives exact signatures and defaults.
• Project notes cover stability, release notes, and known limitations.

Read the guides first when learning. Use the reference when you already know which object or option you need.

Request Lifecycle

Hosted HTTP, MCP, and remote CLI calls enter through the server adapter. Local CLI imports your app and enters after the network layer.

Route groups do not add another router at request time. Quater flattens group prefixes, middleware, auth, metadata, and resources when routes compile.

HTTP requests go from the route to route auth=. MCP and remote CLI requests run their surface auth first, then the same route auth= if the route has one.

One Handler, Three Surfaces

from quater import AuthContext, AuthRequest, Quater, Request


async def authenticate(ctx: AuthRequest) -> AuthContext | None:
    if ctx.headers.get("authorization") != "Bearer demo-token":
        return None
    return AuthContext(subject="demo-user")


app = Quater(mcp_auth=authenticate, cli_auth=authenticate)


@app.get(
    "/orders/{order_id}",
    tool=True,
    cli=True,
    auth=authenticate,
    description="Fetch one order by id.",
)
async def get_order(order_id: str, request: Request) -> dict[str, object]:
    assert request.auth is not None
    return {
        "order_id": order_id,
        "subject": request.auth.subject,
        "source": request.context.source,
        "entrypoint": request.context.entrypoint,
    }

Expected HTTP output:

{
  "order_id": "ord_1001",
  "subject": "demo-user",
  "source": "api",
  "entrypoint": "server"
}

Expected local CLI output:

{
  "order_id": "ord_1001",
  "subject": "demo-user",
  "source": "cli",
  "entrypoint": "local"
}

The three surfaces converge on the same handler, but auth does not collapse:

Reading Path

1. Quickstart: install Quater, run an app, call HTTP, MCP, and CLI.
2. Why Quater Exists: understand the human-and-agent backend model.
3. Routes and Handlers: learn how Quater maps calls to your code.
4. HTTP, MCP, and CLI Surfaces: understand the access paths.
5. Auth Model: review the layered auth rules.
6. Resources and State: add database sessions and other per-request values.
7. MCP and Actions and CLI: expose selected operations to agents and MCP clients.
8. Security, Deployment, and Testing: prepare real apps.
9. Reference: look up signatures and exact defaults.

What Can Go Wrong

MCP tools require mcp_auth : Add mcp_auth=... to Quater(...) before declaring tool=True routes.

CLI actions require cli_auth : Add cli_auth=... before declaring cli=True routes.

needs_approval requires tool=True or cli=True : Use needs_approval=True only on routes exposed as MCP tools or CLI actions.

Dynamic routes at the same position must use the same name and converter : Rename the conflicting path variable or split the route pattern.

Known Limitations

See Known Limitations for the current pre-release gaps, including WebSockets, built-in ORM support, background jobs, rate limiting, MCP streaming, and OpenAPI depth.

Also See

• Quickstart: build the first working app.
• Why Quater Exists: understand the problem Quater is built around.
• Security: understand the auth boundaries shown above.
• Reference: check exact signatures and defaults.