Skip to main content
Pre-release

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.0rc2"   # 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: effect is required and maps to MCP readOnlyHint and destructiveHint.
  • Typed inputs and outputs: Pydantic models in, Pydantic models out, validated both ways.
  • Compact schemas: optional fields are advertised without the anyOf/null noise.
  • Concise by default: fields marked Detail are only returned when the agent asks for response_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 isError result asking for a narrower call instead of broken JSON.
  • Safe pagination: mark the page list Paginated and the cursor Cursor, and use ctx.page(...). If OunceMCP trims the page to fit the budget, it moves next_cursor so the next call resumes after the last item returned. No item is skipped or repeated. Lists are never trimmed below min_items (default 1). Cursors are signed: they expire, and only work for the same tool, caller and filters. Set OUNCEMCP_CURSOR_KEYS in production (proposal 0003).
  • Automatic discovery: OunceServer(discovery="auto") (the default) sends every tool while the definitions fit Budget.startup_tokens. Above it, the server sends search_tools, describe_tool and call_tool instead (279 tokens whatever the catalog), plus any pinned tools. 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, and await 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 retryable flag. 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. Raise InvalidInput, NotFound, RateLimited and the other OunceError classes 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.identity comes 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.cache is partitioned by tenant, ctx.issue_state hands out handles and approvals bound to caller, request and expiry, and HTTP binds to loopback with Host and Origin checks (proposal 0008).
  • Safe writes: idempotency=True runs 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 a preview asks a person first, through the client, and refuses when nobody can be asked (safe writes).
  • Large results and slow work: OunceServer(handles=True) adds handles.read and jobs.get. await ctx.store_result(rows) returns a handle to page, and await ctx.start_job(work) runs work in the background. Both work across replicas with a shared RedisStore.
  • 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, and ouncemcp audit <url | file | -- command> measures any MCP server (migration guide).
  • Many servers: ouncemcp.client.Broker connects 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, /readyz and, with metrics=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.jsonl writes an HTML report you can search and filter (proposal 0020), and OTelSink() exports spans to OpenTelemetry (proposal 0018).
  • Task suites: ouncemcp eval suite.yaml runs 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 example inventory.cost_review returns 651 tokens in 1 call where paging inventory.search takes 9,896 tokens over 8 calls.
  • Testing: ouncemcp.testing.as_caller(...) runs code as a verified caller, and ouncemcp.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.py counts 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

Apache-2.0

Metadata

Release files for ouncemcp 1.0.0rc2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ouncemcp 1.0.0rc2
File Size Uploaded Provenance Actions
ouncemcp-1.0.0rc2.tar.gz 725.1 kB Without provenance Details for ouncemcp-1.0.0rc2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ouncemcp 1.0.0rc2
File Interpreter ABI Platform Actions
ouncemcp-1.0.0rc2-py3-none-any.whl Python 3 none any Details for ouncemcp-1.0.0rc2-py3-none-any.whl

Total release size: 1.1 MB

Release files / ouncemcp-1.0.0rc2.tar.gz

Download URL ouncemcp-1.0.0rc2.tar.gz
Size 725.1 kB
Tags Source
SHA-256 checksum
How to use checksums
10915d74963c5bb472a9734c074bb4c53c3912cc77e20269c4408dc4011bc7f8
BLAKE2b-256 checksum
How to use checksums
f164f345f3ba294a8470d6f909c063fcc42a6a60a4383a71b30a1d6877bef312
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.0rc2-py3-none-any.whl

Download URL ouncemcp-1.0.0rc2-py3-none-any.whl
Size 328.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5914a3b687a4a6548cf4d05625c7b9ff8ec23b32c9cd789cb869c32cd9f5036f
BLAKE2b-256 checksum
How to use checksums
a8c162c998d9fb33fc70f8dfbdbf3051c3ebc0ebcd95cabf3bdb737fe6a84b9c
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.0rc2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page