Skip to content

OunceMCP

Build MCP servers that agents use well: small tool definitions, results that fit the context window, writes that never happen twice, and security that holds when the model is wrong.

Read the Book Quickstart

OunceMCP is a Python framework on FastMCP. Every tool definition and every result is measured in tokens and kept within a budget you set, and writes, approvals and tenant isolation are built in rather than left to each tool.

A tool: typed, bounded, and with an error the model can act on
@server.tool(name="books.get", effect=Effect.READ)
def get(id: str = Field(description="Book id from books.search, for example b-007")) -> BookDetail:
    """Get one book: title, author, subject, year and branch. Use books.search to find ids."""
    book = CATALOG.get(id)
    if book is None:
        raise NotFound(f"No book with id '{id}'.", hint="Use books.search to find ids.")
    return BookDetail(
        id=book.id,
        title=book.title,
        author=book.author,
        subject=book.subject,
        year=book.year,
        branch=book.branch,
    )
$ ouncemcp check examples/book/shelf/step1_catalog.py
Startup context  297 tokens across 2 tools  [OK, budget 4,000]

Tool           Total   Desc  Input  Output  Other  Status
books.search     162     23     54      72     13  OK
books.get        135     21     38      64     12  OK

Where to start

  • The OunceMCP Book


    Learn the framework by building one library server, chapter by chapter. Every stage is a tested file.

    Start reading

  • Quickstart


    ouncemcp init, tests and CI, and a server running in your MCP host in five minutes.

    Get started

  • Reference


    Every public name, every error category and every ouncemcp check lint rule.

    Browse the reference

What you get

  • Measured context

    ouncemcp check counts every definition the way a client receives it, and every result reports the tokens it used.

  • Results that fit

    Results over budget are trimmed and stay valid against their schema. Paged lists resume exactly where the trim stopped.

  • Safe writes

    Approvals ask a person before anything changes; idempotent writes are replayed, never repeated.

  • Security by default

    Identity comes from the verified token, policies hide and refuse tools, and cursors and handles are bound to the caller.

  • Large catalogs

    Above the startup budget, discovery switches to three small search tools automatically.

  • Proof, not claims

    Task suites, a benchmark harness and a trace viewer measure what agents actually do with your server.

Project

The specification holds the requirements, roadmap and milestone status. Design decisions are recorded as proposals, and results are in the M0, M2 and M4 reports. To build this site locally, run uv pip install -e ".[docs]" and then uv run mkdocs serve.