Skip to content

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

from_config(name: str, path: str | Any, **overrides: Any) -> OunceServer

A server whose settings come from ouncemcp.toml at path; keyword arguments override the file. See ouncemcp.core.config.

check_ready async

check_ready() -> list[str]

Names of failing readiness checks: the store, then each readiness check.

wrap classmethod

wrap(mcp: FastMCP, *, effects: Mapping[str, Effect] | None = None, **kwargs: Any) -> OunceServer

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

add_trace_sink(sink: TraceSink) -> None

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

job(name: str, *, max_attempts: int = 3) -> Callable[[Any], Any]

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

budget_overrides() -> dict[str, BudgetOverride]

Each tool's own budget and its reason (BUD-4).

catalog async

catalog() -> list[Any]

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

discovery() -> DiscoveryDecision

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

measure_recall(cases: Sequence[RecallCase], *, k: int | None = None) -> RecallReport

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

list_tools() -> list[Any]

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

cost_report() -> ServerCost

Measure the token cost of this server's tool definitions.

call_tool async

call_tool(name: str, arguments: dict[str, Any] | None = None) -> ToolResult

Call a tool in-process (useful for tests).

http_app

http_app(**kwargs: Any) -> Any

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

"concise" or "detailed". Handlers can skip expensive lookups for fields that will not be returned; see includes (RES-11).

result_budget int

Token budget for this call's result: the tool's concise budget, or Budget.result_ceiling for detailed results. Handlers can use it to choose how much to fetch (RES-11).

fastmcp Context | None

The underlying FastMCP context, when running inside a server.

detailed property

detailed: bool

True when the caller asked for response_format="detailed".

identity property

identity: Identity

The verified caller (SEC-1): principal, tenant, scopes and claims from the access token. Anonymous when the request has no verified token.

cache property

cache: CacheView

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

deps: Any

The server's dependencies (OunceServer(deps=...)): upstream clients, pools and anything else handlers need. Replace them with fakes in tests.

store property

store: OunceStore

The server's shared store (OunceServer(store=...)).

input_responses property

input_responses: Any

The client's answers to a previous require_input (MCP 2026-07-28).

principal property

principal: str

The verified caller that pagination cursors are bound to (resolved once).

includes

includes(path: str) -> bool

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_result(items: Sequence[Any], *, ttl_s: int = DEFAULT_HANDLE_TTL_S) -> str

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

consume_state(token: str, kind: str, *, request: Any = None) -> dict[str, Any]

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

gather(steps: Mapping[str, Callable[[], Awaitable[T]]], *, concurrency: int = 4) -> dict[str, T]

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

effect_applied() -> None

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

require_input(input_requests: Any, *, state: Mapping[str, Any] | None = None) -> typing.NoReturn

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

resume_state() -> dict[str, Any] | None

The state passed to the last require_input, verified, or None.

remaining

remaining() -> float

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

encode_cursor(offset: int, *, ignore: Sequence[str] = ()) -> str

Issue a signed cursor that resumes at offset for this call's tool, caller and arguments.

offset

offset(cursor: str | None, *, ignore: Sequence[str] = ()) -> int

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

annotations() -> dict[str, bool]

Return the MCP tool annotations that describe this effect.

is_parallel_safe

is_parallel_safe(tool: Any) -> bool

Whether a tool definition (an MCP Tool or its JSON) is marked parallel-safe.

Detail module-attribute

Detail = _DetailMarker()

Mark an output field as detail-only: tags: Annotated[dict | None, Detail] = None.

Paginated module-attribute

Paginated = _Marker('Paginated')

Mark the list field that holds one page: items: Annotated[list[X], Paginated].

Cursor module-attribute

Cursor = Annotated[str | None, _CURSOR]

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

ephemeral(*, ttl_s: int = DEFAULT_TTL_S, clock: Callable[[], float] = time.time) -> CursorSigner

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

bind(*, tool: str, principal: str, query: Mapping[str, Any] | None = None) -> BoundCursors

Cursors for one call: valid only for this tool, caller and query.

PageWindow dataclass

PageWindow(items: list[T], start: int, total: int | None, next_cursor: str | None)

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: auto, direct or search.

mode DiscoveryMode

What the server does: direct or search.

direct_tokens int

Definition tokens of every registered tool, as direct mode would send them at startup.

search_tokens int

Definition tokens of the three meta-tools plus pinned tools, as search mode sends them at startup.

threshold int

The startup budget (Budget.startup_tokens) that auto compares direct_tokens with.

pinned tuple[str, ...]

Tools listed in search mode alongside the meta-tools.

reason str

One sentence explaining the choice, for logs and check.

RecallCase dataclass

RecallCase(query: str, expected: frozenset[str] | set[str])

One search task: query should surface every tool in expected.

RecallReport dataclass

RecallReport(k: int, cases: tuple[CaseRecall, ...])

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 ResultTooLarge instead of cutting the text when the smallest valid result does not fit. Defaults to validator is not None.

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 page is not available.

None
assume_valid bool

Treat the untouched result as valid instead of checking it first. Set it only when value is a model instance Pydantic already validated. Each change is still checked.

False