This release is a pre-release and may not be stable for production use.
OunceMCP
Every token counts. OunceMCP is a framework for building Model Context Protocol (MCP) servers and clients that are fast, low-noise, and safe for agents by default. It builds on FastMCP and the official MCP Python SDK, and targets the MCP 2026-07-28 specification.
Status: pre-1.0 (M0 to M4 built). The framework, safe writes, jobs, the client broker, the eval kit, the trace viewer and the benchmark work and are tested; the official MCP conformance suite passes in CI and the M4 performance gates are met (M4 report). The 1.0 API is frozen (proposal 0029, changelog); 1.0 ships after the external security review. Release gates that need people or outside systems are listed in the spec (section 14.2). New here? Read The OunceMCP Book.
Why
Most MCP slowdowns don't come from the protocol. They come from loading every tool definition up front, returning large raw results, and making the model chain many small calls. OunceMCP makes the efficient design the default one:
- Context budgets: token limits for tool definitions, the startup catalog, and each result, checked in CI.
- Automatic discovery: switches from exposing every tool to search-then-call once the catalog is too large.
- Response shaping: concise results by default, field selection, pagination, truncation notes, and handles for large data.
- Safe execution: declared effects, deadlines, bounded retries, idempotent writes, and approvals.
- Visibility: see exactly what the model received and what it cost.
- Optional audit: measure any MCP server, including ones not built with OunceMCP.
Quickstart
pipx install "ouncemcp==1.0.0rc1" # or: uv tool install --prerelease allow ouncemcp
ouncemcp init notes-server && cd notes-server
uv venv && uv pip install --prerelease allow -e ".[dev]"
uv run pytest && uv run ouncemcp dev server.py
The full walkthrough is in docs/quickstart.md. To learn the framework step by step, read The OunceMCP Book: one library server built across 15 chapters, every stage tested. A tool looks like this:
from typing import Annotated
from pydantic import BaseModel, Field
from ouncemcp import Cursor, Detail, Effect, OunceServer, Paginated, ToolContext
server = OunceServer("inventory")
class SearchInput(BaseModel):
region: str = Field(description="Region, e.g. ap-south-1")
limit: int = Field(20, ge=1, le=50)
cursor: str | None = None
class Resource(BaseModel):
id: str
name: str
status: str
tags: Annotated[dict[str, str] | None, Detail] = None # only with response_format=detailed
class SearchResult(BaseModel):
items: Annotated[list[Resource], Paginated]
next_cursor: Cursor = None
@server.tool(name="inventory.search", effect=Effect.READ, deadline_ms=5_000)
async def search(args: SearchInput, ctx: ToolContext) -> SearchResult:
"""Find cloud resources in a region."""
rows = await load_resources(args.region)
page = ctx.page(rows, cursor=args.cursor, limit=args.limit)
return SearchResult(items=page.items, next_cursor=page.next_cursor)
if __name__ == "__main__":
server.run() # stdio; prints a token budget summary to stderr
What you get:
- Declared effects:
effectis required and maps to MCPreadOnlyHintanddestructiveHint. - Typed inputs and outputs: Pydantic models in, Pydantic models out, validated both ways.
- Compact schemas: optional fields are advertised without the
anyOf/nullnoise. - Concise by default: fields marked
Detailare only returned when the agent asks forresponse_format="detailed". - Result budgets: every result fits its token budget and still matches its output schema. Lists are trimmed first, then long strings, then optional fields, and the agent gets a note saying what was removed and how to get more. If the smallest valid result is still too large, the agent gets an
isErrorresult asking for a narrower call instead of broken JSON. - Safe pagination: mark the page list
Paginatedand the cursorCursor, and usectx.page(...). If OunceMCP trims the page to fit the budget, it movesnext_cursorso the next call resumes after the last item returned. No item is skipped or repeated. Lists are never trimmed belowmin_items(default 1). Cursors are signed: they expire, and only work for the same tool, caller and filters. SetOUNCEMCP_CURSOR_KEYSin production (proposal 0003). - Automatic discovery:
OunceServer(discovery="auto")(the default) sends every tool while the definitions fitBudget.startup_tokens. Above it, the server sendssearch_tools,describe_toolandcall_toolinstead (279 tokens whatever the catalog), plus anypinnedtools. Search results come in three detail levels (name,summary,full) and only include tools the caller is authorized to use (@server.tool(auth=...)). Hiding a tool is not access control: the same check runs on a guessed name.discovery="direct"or"search"overrides the choice, andawait server.measure_recall(cases)reports how often search finds the tools agents need. See proposal 0006. - Categorized errors: every failure is one of validation, authentication, permission, not found, rate limit, transient, ambiguous write or internal, with a
retryableflag. Validation messages say how to fix the input without repeating it. Unexpected exceptions are never shown to the model: it gets a reference id and the details go to the log. Messages you write are redacted for URLs, addresses, hostnames, paths and credentials. RaiseInvalidInput,NotFound,RateLimitedand the otherOunceErrorclasses from handlers. - Execution limits: every call has a deadline (default 30 s) and is cancelled when it passes or the client cancels. Reads are retried a few times with bounded backoff inside the deadline, and writes never are. A write that times out is reported as ambiguous, not as failed. Request size, nesting depth and calls in flight per principal are bounded (
Limits). See proposal 0007. - Security and policy:
ctx.identitycomes from the verified token only.policy=on the server or a tool decides who sees and calls it, on the declared effect, never on annotations.audience=refuses tokens issued for other servers,passthrough_guard()stops the caller's token from reaching upstream APIs,ctx.cacheis partitioned by tenant,ctx.issue_statehands out handles and approvals bound to caller, request and expiry, and HTTP binds to loopback withHostandOriginchecks (proposal 0008). - Safe writes:
idempotency=Trueruns a write once per caller and arguments, and a write that times out finishes in the background so a retry gets its result instead of writing twice.approval="required"with apreviewasks a person first, through the client, and refuses when nobody can be asked (safe writes). - Large results and slow work:
OunceServer(handles=True)addshandles.readandjobs.get.await ctx.store_result(rows)returns a handle to page, andawait ctx.start_job(work)runs work in the background. Both work across replicas with a sharedRedisStore. - Resources and prompts:
@server.resource(uri)and@server.prompt()get the same budgets, policies and verified caller as tools. - Migration and audit:
OunceServer.wrap(existing_fastmcp_server)adds all of the above without touching its tools, andouncemcp audit <url | file | -- command>measures any MCP server (migration guide). - Many servers:
ouncemcp.client.Brokerconnects a host to many servers as one catalog, with namespaced tools, cross-server search, schema checks, deadlines, failure isolation, and no cross-server authority from server output (broker). - Operations:
OunceServer.from_config(name, "ouncemcp.toml"),/healthz,/readyzand, withmetrics=True, Prometheus/metrics(deploying). - Traces:
OunceServer(trace=MemorySink())records each call's result tokens, latency, retries and outcome, redacted by default (proposal 0009).ouncemcp trace calls.jsonlwrites an HTML report you can search and filter (proposal 0020), andOTelSink()exports spans to OpenTelemetry (proposal 0018). - Task suites:
ouncemcp eval suite.yamlruns YAML tasks against a server, judges outcomes on the server, and reports success, tool choice, tokens, latency and regressions against a baseline (proposal 0019). - Composite tools:
ctx.gather(...)runs several upstream calls in one tool call. The exampleinventory.cost_reviewreturns 651 tokens in 1 call where paginginventory.searchtakes 9,896 tokens over 8 calls. - Testing:
ouncemcp.testing.as_caller(...)runs code as a verified caller, andouncemcp.eval.run_security_suite(server, cases)probes for cross-tenant leaks, guessed names, cursor and handle reuse, replay, token passthrough and SSRF. - Budget checks:
ouncemcp check server.pycounts the tokens of every tool definition as the host receives it, and fails CI when a tool goes over budget or a lint error is found. It also reports which discovery mode the server will use and why. Every lint and error links to a page explaining it.
ouncemcp check examples/inventory/server.py
ouncemcp context examples/inventory/server.py inventory.search
ouncemcp context examples/inventory/server.py --html context.html # every tool, as a page
ouncemcp dev examples/inventory/server.py # hot reload, live per-call token lines
Counts use o200k_base by default. Choose another tiktoken encoding with OunceServer(tokenizer="cl100k_base") or ouncemcp check --tokenizer cl100k_base, or pass your own counting function with tokenizer=fn, tokenizer_name="my-tokenizer-v1". Every report names the tokenizer it used (proposal 0004).
ouncemcp audit is the optional command for measuring any server. ouncemcp eval runs task suites, with the replay model or real models through OpenRouter, ouncemcp bench compares servers across models, and ouncemcp trace reads traces.
Benchmark (M3)
Two pilot servers against their plain FastMCP equivalents: four models (Claude Haiku 5.5, Claude Sonnet 5.5, GPT-5.4 mini, DeepSeek V4.1 Flash), 21 tasks, 5 runs each, success judged on outcomes. See the full results and caveats.
| Inventory (large results) | Ticketing (writes, small results) | |
|---|---|---|
| Tokens per task, OunceMCP vs plain | 58–85% fewer | 17–40% more |
| Task success, OunceMCP vs plain | 100% vs 75–100% | 100% vs 68–70% |
| Tool definitions, OunceMCP vs plain | 584 vs 244 tokens | 649 vs 366 tokens |
On these small servers the definitions are larger, mostly from output schemas. PERF-6, revised for small servers (definitions at most 2× plain, no drop in success), is met for ticketing and missed for inventory at 2.4× (proposal 0027). On the plain ticketing server every model skipped the approval, deleted without permission and read another team's ticket.
M0 results
Measured on the inventory example with the o200k_base tokenizer. Full method and caveats are in docs/m0-report.md.
| OunceMCP | Plain FastMCP | |
|---|---|---|
| Tool definitions (2 tools) | 488 tokens | 195 tokens |
| Four-task session, definitions plus results | 1,510 tokens | 32,280 tokens |
| Added server time per call, p50 / p95 | 0.14–0.44 ms / 0.07–0.47 ms (1.44 / 1.32 ms when truncating) | baseline |
In M1, results that are trimmed must still match the output schema. Truncated calls now add 0.70 / 0.80 ms (p50 / p95) and other calls 0.14 to 0.31 ms. Shaping a 36,000-token result down to a 2,000-token budget takes 7.3 ms. See proposal 0002 and benchmarks/scripts/m1_truncation.py.
Typed output schemas make definitions larger. Results are where the savings come from. Output schemas can be set to "on" (default), "off" or "auto" for a server (output_schemas=) or one tool (output_schema=). In M1, "off" gave 247 tokens for this example, and "auto", which drops a schema only where it would put a definition over the per-tool target, gave 378. ouncemcp check reports the output-schema share of definition tokens (241 of 504 in the current example) and states which fields it counts: name, description, inputSchema and outputSchema, not title, annotations or _meta (proposal 0005).
Repository layout
src/ouncemcp/
core/ capabilities, budgets, response shaping, token accounting, errors, lints,
resources and prompts, config file
security/ identity, policy, audience and passthrough, caches, bound state, HTTP
defaults, stdio policy, URL checks
discovery/ direct and search discovery modes
execution/ deadlines, retries, limits, middleware, store, idempotency, approvals,
handles and jobs
trace/ per-call traces, redaction and metrics
eval/ conformance target, security test catalog and agent task suites
cli/ init, dev, check, context, audit, eval, trace (bench planned)
client/ reference client broker
audit/ optional audit command
testing.py as_caller and make_token for tests
examples/ pilot servers: inventory, ticketing, report, markitdown migration
benchmarks/ servers, tasks, scripts, published results
docs/ specification, research, concepts, guides, proposals
tests/
Roadmap
| Milestone | Scope | Status |
|---|---|---|
| M0: core spike | OunceServer, typed tools with effects, token counting, result budgets, one example server |
Built (M0 report) |
| M1: v0.1 | Framework core, automatic discovery, errors, security, init/dev/check/context, docs |
Built |
| M2: v0.2 | Safe writes, client broker, migration guide, pilots, optional audit |
Built (M2 report) |
| M3: v0.5 | Eval kit, trace viewer, public benchmark, launch | Built (benchmark); launch waits on the repository going public |
| M4: v1.0 | Security review, host compatibility matrix, stable API, the book | API frozen (0029), all release gates checked, release workflow ready (M4 report); waiting on the external security review |
The full plan is in docs/spec.md, and the supporting research is in docs/performance-research.md.
Development
uv venv && uv pip install -e ".[dev]"
uv run pytest
uv run ruff check .
uv pip install -e ".[docs]" && uv run mkdocs serve # documentation site
python benchmarks/scripts/m0_compare.py # token comparison
python benchmarks/scripts/m0_overhead.py # per-call overhead
Contributing
See CONTRIBUTING.md. Security issues: see SECURITY.md.
License
Metadata
Release files for ouncemcp 1.0.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ouncemcp-1.0.0rc1.tar.gz | 724.7 kB | Without provenance | Details for ouncemcp-1.0.0rc1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ouncemcp-1.0.0rc1-py3-none-any.whl | Python 3 | none | any | Details for ouncemcp-1.0.0rc1-py3-none-any.whl |
Total release size: 1.1 MB
Release files / ouncemcp-1.0.0rc1.tar.gz
| Download URL | ouncemcp-1.0.0rc1.tar.gz |
|---|---|
| Size | 724.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d4700091a239336528b08d62c78265410ee19dc6e00e41ed743a38854f55204a
|
|
BLAKE2b-256 checksum How to use checksums |
cd21fc225f872bfbec08bc77013ef5e43fd1f51bddca24d3c76b0beeae72e756
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ouncemcp-1.0.0rc1-py3-none-any.whl
| Download URL | ouncemcp-1.0.0rc1-py3-none-any.whl |
|---|---|
| Size | 328.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7622c639ac7db98df5ab4a7680a9bdb7e2fada6fe552fd13049665acb149a68e
|
|
BLAKE2b-256 checksum How to use checksums |
60a21badecd6b3bc77514b847cc36c86e6f100bdcf81d046ae0024d11dc50965
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for ouncemcp 1.0.0rc1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.