Server and tools¶
Stable
Covered by the 1.0 API freeze (proposal 0029): no breaking change before 2.0.
OunceServer ¶
OunceServer(name: str, *, instructions: str | None = None, version: str | None = None, budget: Budget | None = None, tokenizer: str | TokenCounter | Callable[[str], int] = DEFAULT_ENCODING, tokenizer_name: str | None = None, output_schemas: bool | OutputSchemaMode = 'on', cursors: CursorSigner | None = None, principal: PrincipalResolver | None = None, discovery: DiscoverySetting = 'auto', pinned: Sequence[str] = (), search_results: int = 5, limits: Limits | None = None, retry: RetryPolicy | None = None, write_resolver: WriteResolver | None = None, policy: Policy | Sequence[Policy] | None = None, audience: str | Sequence[str] | None = None, tenant_claims: Sequence[str] = DEFAULT_TENANT_CLAIMS, cache: PartitionedCache | None = None, trace: Tracer | TraceSink | Sequence[TraceSink] | None = None, stdio_policy: StdioPolicy = 'trust', store: OunceStore | None = None, deps: Any = None, approver: Approver | None = None, handles: bool = False, metrics: bool = False, readiness: Sequence[Callable[[], Any]] = (), http_host: str = '127.0.0.1', **fastmcp_kwargs: Any)
An MCP server whose tools are typed, effect-declared, and context-budgeted.
Example::
server = OunceServer("inventory", budget=Budget(result_tokens=1_500))
@server.tool(name="inventory.search", effect=Effect.READ)
async def search(args: SearchInput, ctx: ToolContext) -> SearchResult:
"""Find resources by region and type."""
...
server.run()
Token counts use tokenizer: a tiktoken encoding name (default o200k_base),
a TokenCounter, or a function from text to token count, which also needs
tokenizer_name so reports can name it. Budgets, shaping and check all use it.
from_config
classmethod
¶
A server whose settings come from ouncemcp.toml at path; keyword
arguments override the file. See ouncemcp.core.config.
check_ready
async
¶
Names of failing readiness checks: the store, then each readiness check.
wrap
classmethod
¶
Put an existing FastMCP server under OunceMCP without changing its tools.
Step 1 of a migration (DX-7). The wrapped server keeps its tools as they are and
gains token accounting (check, dev, cost_report), categorized and
redacted errors, request limits, traces and automatic discovery. Name each
tool's effect in effects; a tool without one is treated as a read, so a
timeout is reported as transient instead of ambiguous_write. Tools added
to mcp after wrapping are served but not measured until wrapped again.
mcp itself is changed (OunceMCP's middleware and transforms are added to
it), so wrap a server once and serve the returned OunceServer. Then move
tools to @server.tool one at a time.
add_trace_sink ¶
Send traces to one more sink, creating a tracer if the server had none.
tool ¶
tool(fn: Callable[..., Any] | None = None, *, effect: Effect | None = None, name: str | None = None, description: str | None = None, title: str | None = None, result_tokens: int | None = None, deadline_ms: int | None = None, tags: set[str] | None = None, min_items: int = 1, output_schema: OutputSchemaMode | None = None, auth: AuthCheck | list[AuthCheck] | None = None, policy: Policy | Sequence[Policy] | None = None, replay_safe: bool = False, idempotency: bool | Idempotency | None = None, approval: ApprovalRule = 'never', preview: Preview | None = None, definition_tokens: int | None = None, budget_reason: str | None = None, parallel_safe: bool | None = None) -> Any
Register a tool. effect is required.
parallel_safe marks the tool as safe for clients to call in parallel with
other calls, in _meta["ouncemcp/parallelSafe"] (EXE-5). Read tools are
parallel-safe unless they depend on call order (a shared queue, a cursor kept on
the server); set parallel_safe=False for those. Writes are never marked.
result_tokens and definition_tokens give this tool its own budget (BUD-4):
the concise result budget, and the definition size above which ouncemcp check
fails. Raising either above the server's budget needs budget_reason, which
check reports next to the tool; without one, registration warns.
policy decides who may see and call the tool, in addition to the server's
policy (all must allow). It gets the declared effect and the verified caller,
never the MCP annotations (SEC-2, SEC-3). replay_safe=True declares that the
handler can run again after an effect without repeating it, which lets a write
tool ask for input after ctx.effect_applied() (SEC-7).
output_schema sets whether this tool advertises its output schema: "on",
"off", or "auto" (advertise it unless the definition would then be over
Budget.tool_definition_target). It defaults to the server's output_schemas.
auth is a FastMCP authorization check (or a list, all of which must pass).
It decides who can see the tool in lists and search results, and who can call it,
including by a guessed name.
The handler can take either a single Pydantic model argument (its fields
become the tool's top-level arguments) or ordinary keyword arguments, plus
an optional ToolContext parameter. It must be annotated to return a
Pydantic model, which defines the tool's output schema.
resource ¶
resource(uri: str, *, name: str | None = None, description: str | None = None, mime_type: str | None = None, max_tokens: int | None = None, policy: Policy | Sequence[Policy] | None = None, tags: set[str] | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]
Register a resource (CAP-2). {placeholders} in uri make a template.
The handler returns str, bytes, a model, a dict or a list. Text over
max_tokens (default Budget.result_ceiling) is cut with a note; JSON over
it is refused. policy works as for tools. See ouncemcp.core.primitives.
prompt ¶
prompt(name: str | None = None, *, description: str | None = None, max_tokens: int | None = None, policy: Policy | Sequence[Policy] | None = None, tags: set[str] | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]
Register a prompt (CAP-2). Its arguments come from the handler's parameters;
prompts over max_tokens are refused. policy works as for tools.
job ¶
Register a named background job that resumes after a restart.
fn(args) or fn(args, attempt) runs the job; args is the dict passed to
ctx.start_job(name, args), or a Pydantic model if the parameter is annotated
with one. If the process running it stops, the next jobs.get (on any
replica) starts it again from the beginning, up to max_attempts runs in all,
so the job must be safe to repeat. Needs OunceServer(handles=True).
budget_overrides ¶
Each tool's own budget and its reason (BUD-4).
catalog
async
¶
Every registered tool's definition, whatever the discovery mode and whoever asks.
This is what direct mode sends over stdio. check measures it so that
per-tool budgets apply to tools that search mode only sends on request.
discovery
async
¶
The discovery mode in force, and the measurements that decided it (DISC-1).
Measured on the whole registered catalog, not per caller, so the mode and the meta-tool list do not change from one principal to the next (DISC-5). Recomputed after any tool is registered.
measure_recall
async
¶
Search recall at k over the whole catalog (DISC-6).
k defaults to the server's search_results. Works in either mode, so it
can inform the choice. Pinned tools are not part of the search index.
list_tools
async
¶
Return the MCP tool definitions exactly as clients receive them.
Definitions are fetched through an in-memory MCP client, so field order and serialization match the wire and token counts match a host-side recount.
cost_report
async
¶
Measure the token cost of this server's tool definitions.
call_tool
async
¶
Call a tool in-process (useful for tests).
http_app ¶
The ASGI app for HTTP transports, with Host and Origin validation on
(SEC-8). Pass allowed_hosts and allowed_origins for a public deployment.
run ¶
run(transport: Literal['stdio', 'http', 'sse', 'streamable-http'] = 'stdio', *, check_budget: bool = True, **kwargs: Any) -> None
Run the server. Prints a budget summary to stderr (stdout stays protocol-only).
HTTP transports bind to 127.0.0.1 and validate Host and Origin by
default (SEC-8). Binding another address needs allowed_hosts.
ToolContext
dataclass
¶
ToolContext(tool: str, response_format: ResponseFormat, result_budget: int, fastmcp: Context | None = None, _signer: CursorSigner | None = None, _arguments: Callable[[], Mapping[str, Any]] = dict, _resolve: PrincipalResolver = default_principal, _principal: str | None = None, attempt: int = 1, _deadline_at: float | None = None, _window: PageWindow[Any] | None = None, _encode: Callable[[int], str] | None = None, _bound: dict[frozenset[str], BoundCursors] = dict(), effect: Effect | None = None, replay_safe: bool = False, _identity: Identity | None = None, _tenant_claims: tuple[str, ...] = DEFAULT_TENANT_CLAIMS, _cache: PartitionedCache | None = None, _state: StateSigner | None = None, _deps: Any = None, _store: OunceStore | None = None, _effects_applied: bool = False, _approved: bool = False, _jobs: JobRunner | None = None, _output_model: type[BaseModel] | None = None)
Per-call information passed to handlers that declare a ToolContext parameter.
Attributes:
| Name | Type | Description |
|---|---|---|
tool |
str
|
The tool name. |
response_format |
ResponseFormat
|
|
result_budget |
int
|
Token budget for this call's result: the tool's concise budget,
or |
fastmcp |
Context | None
|
The underlying FastMCP context, when running inside a server. |
identity
property
¶
The verified caller (SEC-1): principal, tenant, scopes and claims from the access token. Anonymous when the request has no verified token.
cache
property
¶
The server's private cache, partitioned by this caller's principal, tenant and scopes and namespaced by tool, so entries never cross callers (SEC-5).
deps
property
¶
The server's dependencies (OunceServer(deps=...)): upstream clients, pools
and anything else handlers need. Replace them with fakes in tests.
input_responses
property
¶
The client's answers to a previous require_input (MCP 2026-07-28).
principal
property
¶
The verified caller that pagination cursors are bound to (resolved once).
includes ¶
Whether output field path is returned in this call (RES-11).
path names a field of the tool's output model, dotted for nested models
("owner.history"). Fields marked Detail are only returned in detailed
results, so a handler can skip the lookup that fills them::
if ctx.includes("metrics"):
detail.metrics = await fetch_metrics(id)
Unknown fields raise ValueError, so a renamed field cannot silently turn a
lookup off.
store_result
async
¶
Store a large result and return a handle the caller pages with
handles.read (RES-5). Needs OunceServer(handles=True). The handle is
bound to this caller and tenant and expires after ttl_s.
start_job
async
¶
start_job(work: Callable[[], Awaitable[Any]] | str, args: Mapping[str, Any] | None = None, *, ttl_s: int = DEFAULT_JOB_TTL_S) -> str
Run a job in the background and return a job id for jobs.get.
work is either a function to run, or the name of a job registered with
@server.job plus its JSON args. A named job is started again by the next
jobs.get if its process stops; a function cannot be, and is reported
interrupted. The job returns a model or dict (the summary) or a
JobResult with a summary and many items, which are stored behind a handle.
Needs OunceServer(handles=True). The id is bound to this caller and tenant.
consume_state
async
¶
Like verify_state(..., consume=True), but single use is recorded in the
shared store, so it holds across replicas when the store is shared (SEC-6).
issue_state ¶
issue_state(kind: str, data: Mapping[str, Any] | None = None, *, request: Any = None, ttl_s: int | None = None) -> str
Issue a signed token for a handle, approval or continuation (SEC-6).
It is bound to this caller, to request (any JSON value that identifies the
originating request; default: this tool), and expires after ttl_s.
verify_state ¶
verify_state(token: str, kind: str, *, request: Any = None, consume: bool = False) -> dict[str, Any]
Return the data of a token from issue_state, or raise InvalidState,
which the caller sees as an actionable validation error. consume=True makes
the token single-use, which blocks replay of an approval.
gather
async
¶
Run the steps of a composite tool concurrently and return their results by name.
Each step is a function returning an awaitable, such as one upstream call. At most
concurrency run at once, all inside this call's deadline (EXE-1). If a step
fails, the others are cancelled and the error is classified like any handler
error, so one composite call costs the agent one round trip whichever way it
ends (spec CAP-7).
effect_applied ¶
Record that this call changed something outside the server.
Call it right after an irreversible upstream effect. Afterwards a write tool that
is not replay_safe may not ask for input (SEC-7), because the client answers
by sending the whole request again, which would repeat the effect.
require_input ¶
Stop and ask the client for input (MCP multi-round-trip, SEP-2322).
Raises an exception the server turns into an input_required result; the client
answers by repeating this call with input_responses. state is signed and
bound to this caller and these arguments (SEC-6); read it back with
resume_state(). Refused after effect_applied() unless the tool is
replay_safe (SEC-7).
resume_state ¶
The state passed to the last require_input, verified, or None.
remaining ¶
Seconds left before this call's deadline, or inf when it has none.
Pass it to upstream timeouts so a slow dependency gives up when the call would.
encode_cursor ¶
Issue a signed cursor that resumes at offset for this call's tool, caller
and arguments.
offset ¶
Verify a cursor issued by this tool and return its start offset (None is 0).
Cursors are bound to the tool, the caller and every argument except cursor,
limit, response_format and the names in ignore. Raises
InvalidCursor, which the server returns as an actionable tool error.
page ¶
page(rows: Sequence[T], *, cursor: str | None, limit: int, ignore: Sequence[str] = ()) -> PageWindow[T]
Slice one page from rows. If OunceMCP trims the page to fit the result
budget, it moves next_cursor to resume after the last item returned.
Name any paging arguments that are not called cursor or limit in
ignore, so changing them does not invalidate the cursor.
window ¶
window(items: Sequence[T], *, start: int, has_more: bool, total: int | None = None, ignore: Sequence[str] = ()) -> PageWindow[T]
Register a page fetched elsewhere (for example OFFSET start LIMIT n).
Effect ¶
Bases: str, Enum
What a tool does to the outside world. Every tool must declare one.
annotations ¶
Return the MCP tool annotations that describe this effect.
is_parallel_safe ¶
Whether a tool definition (an MCP Tool or its JSON) is marked parallel-safe.
Detail
module-attribute
¶
Mark an output field as detail-only: tags: Annotated[dict | None, Detail] = None.
Paginated
module-attribute
¶
Mark the list field that holds one page: items: Annotated[list[X], Paginated].
Cursor
module-attribute
¶
Type for the next-page cursor field: next_cursor: Cursor = None.
CursorSigner ¶
CursorSigner(keys: Sequence[str | bytes], *, ttl_s: int = DEFAULT_TTL_S, clock: Callable[[], float] = time.time, _ephemeral: bool = False)
Issues and verifies cursors with HMAC keys.
keys is newest first: the first key signs, every key verifies, so a key can be
rotated by adding the new one in front and removing the old one once its cursors
have expired (after ttl_s).
ephemeral
classmethod
¶
A random key that lives as long as the process. For development only.
from_env
classmethod
¶
from_env(env: Mapping[str, str] | None = None, *, ttl_s: int = DEFAULT_TTL_S, clock: Callable[[], float] = time.time) -> CursorSigner
Read comma-separated keys, newest first, from OUNCEMCP_CURSOR_KEYS.
Without that variable the signer uses a random per-process key and warns the first time a cursor is issued.
bind ¶
Cursors for one call: valid only for this tool, caller and query.
PageWindow
dataclass
¶
Bases: Generic[T]
DiscoveryDecision
dataclass
¶
DiscoveryDecision(setting: DiscoverySetting, mode: DiscoveryMode, direct_tokens: int, search_tokens: int, threshold: int, pinned: tuple[str, ...], reason: str)
Which discovery mode a server uses, and the measurements behind the choice.
Attributes:
| Name | Type | Description |
|---|---|---|
setting |
DiscoverySetting
|
What the developer asked for: |
mode |
DiscoveryMode
|
What the server does: |
direct_tokens |
int
|
Definition tokens of every registered tool, as |
search_tokens |
int
|
Definition tokens of the three meta-tools plus pinned tools, as
|
threshold |
int
|
The startup budget ( |
pinned |
tuple[str, ...]
|
Tools listed in |
reason |
str
|
One sentence explaining the choice, for logs and |
RecallCase
dataclass
¶
One search task: query should surface every tool in expected.
RecallReport
dataclass
¶
Recall at k over a set of cases.
shape_result ¶
shape_result(value: Any, *, response_format: ResponseFormat, budget: int, counter: TokenCounter, validator: Validator | None = None, strict: bool | None = None, min_items: int = 1, page: PageSpec | None = None, protect: Collection[str] = (), cursor_hint: str | None = None, assume_valid: bool = False) -> ShapedResult
Shape value so its serialized text, plus any truncation note, fits in
budget tokens.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
validator
|
Validator | None
|
Validator for the advertised output schema. Every change is checked against it and reverted if it would make the result invalid. |
None
|
strict
|
bool | None
|
Raise |
None
|
min_items
|
int
|
Never trim a non-empty list below this many items (RES-10). |
1
|
page
|
PageSpec | None
|
Framework-issued pagination to keep consistent while trimming. |
None
|
protect
|
Collection[str]
|
Top-level keys that are never shortened or dropped. |
()
|
cursor_hint
|
str | None
|
Name of a handler-managed cursor field, used to warn that it
skips trimmed items when |
None
|
assume_valid
|
bool
|
Treat the untouched result as valid instead of checking it
first. Set it only when |
False
|