

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.
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.
@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.
-
Quickstart
ouncemcp init, tests and CI, and a server running in your MCP host in five minutes. -
Reference
Every public name, every error category and every
ouncemcp checklint rule.
What you get¶
-
Measured context
ouncemcp checkcounts 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.