Security and policy¶
All of this is in ouncemcp.security. Design: proposal 0008.
| Requirement | What OunceMCP does |
|---|---|
| SEC-1 Verified identity | ctx.identity comes only from the verified access token: principal (issuer and subject), tenant, scopes, claims. clientInfo is never used |
| SEC-2 Policy on lists and calls | policy= on the server and on tools; one decision hides the tool from lists and search and refuses calls |
| SEC-3 Annotations are hints | Policies see the effect declared at registration, never MCP annotations |
| SEC-4 Audience, no passthrough | OunceServer(audience=...) checks aud/resource; check_outbound and passthrough_guard() block forwarding the caller's token |
| SEC-5 Partitioned caches | ctx.cache is keyed by principal, tenant and scopes |
| SEC-6 Bound state | ctx.issue_state / ctx.verify_state: tokens bound to caller, request and expiry; consume=True for single use |
| SEC-7 Replay-safe effects | ctx.require_input refuses to ask after ctx.effect_applied() unless the tool is replay_safe |
| SEC-8 HTTP defaults | Bind 127.0.0.1, validate Host and Origin; public binds need allowed_hosts |
| SEC-11 Trace redaction | See traces |
| SEC-12 Signed cursors | See shaping |
from ouncemcp.security import authenticated, require_scopes, writes_require
server = OunceServer(
"tickets",
audience="https://mcp.example.com",
policy=writes_require(authenticated),
)
@server.tool(name="tickets.purge", effect=Effect.DESTRUCTIVE, policy=require_scopes("admin"))
async def purge(ctx: ToolContext) -> Purged: ...
Policies apply over HTTP and to in-process calls. Over stdio FastMCP skips component authorization, because the server runs as the local user who started it, so by default (stdio_policy="trust") every tool is visible and callable there. Set OunceServer(stdio_policy="enforce") to apply every check on stdio with the anonymous caller. ouncemcp check warns when tools have policies and stdio is trusted (stdio-skips-policy).
Fetching URLs the model chose (SEC-9). safe_client(allow_hosts=[...]) is an HTTP client that refuses private, loopback, link-local and metadata addresses, connects only to the address it checked, and checks every redirect again (proposal 0023).
OAuth (SEC-10). Protect a server with one of FastMCP's maintained providers, OunceServer(auth=GitHubProvider(...)); policies then read the identity it verifies. Clients sign in with ouncemcp.client.OunceOAuth, which uses a pre-registered client id first, then a Client ID Metadata Document, and dynamic registration only as a last resort (allow_dynamic=False refuses it); ouncemcp audit URL --oauth does the same from the command line (proposal 0025).
Test policies with ouncemcp.testing.as_caller(subject=..., tenant=..., scopes=[...]), and probe a whole server with the security catalog.