Migrating from FastMCP¶
Move an existing FastMCP server (or a server written with the MCP Python SDK's FastMCP-style MCPServer) to OunceMCP in small steps. Every step is a working server, and ouncemcp audit measures each one. The worked example is markitdown-mcp.
Step 0: measure what you have¶
ouncemcp audit path/to/server.py:mcp --output before.json # in-process
ouncemcp audit -- python path/to/server.py # or over stdio
ouncemcp audit https://mcp.example.com/mcp --bearer "$TOKEN" # or a deployed server
audit reports startup tokens per tool and field, resources and prompts, schema bloat, latency and a discovery recommendation. It only lists tools; add --sample tool='{"arg": 1}' to measure real result sizes.
Step 1: wrap it, unchanged¶
from original import mcp
from ouncemcp import Effect, OunceServer
server = OunceServer.wrap(mcp, effects={"add_note": Effect.WRITE, "get_note": Effect.READ})
server.run()
No tool code changes. You get ouncemcp check and ouncemcp dev, categorized and redacted errors (exception text no longer reaches the model), deadlines, request limits, traces and automatic discovery. Name every write in effects, so a write that times out is reported as ambiguous_write.
Step 2: move one tool to @server.tool¶
@server.tool(name="convert_to_markdown", effect=Effect.READ)
async def convert_to_markdown(uri: str, ctx: ToolContext) -> Converted:
...
Keep the tool name, so hosts and prompts keep working. Give it a Pydantic output model: results are now shaped to the budget and match their output schema. Mark rarely needed fields Detail. Repeat for each tool; wrapped and moved tools can be served side by side while you go.
Step 3: bound what comes back¶
- Lists: mark the list
Paginatedand the cursorCursor, and page withctx.page(...). - Large documents or exports:
OunceServer(handles=True)and returnawait ctx.store_result(chunks); the agent reads on withhandles.read. - Slow work:
await ctx.start_job(work)andjobs.get.
Step 4: make it safe¶
- URLs from the model:
check_url(uri)refuses loopback, private, link-local and metadata addresses; fetch them withsafe_client(), which connects only to the checked address and checks every redirect (proposal 0023). - Upstream HTTP:
deps=...withguarded_client(...), so the caller's token is never forwarded. - Writes:
idempotency=True, andapproval="required"with apreviewfor anything a person should confirm (safe writes). - Who may call what:
policy=(securing tools).
Step 5: compare¶
markitdown-mcp, measured¶
| Original | Step 1 (wrapped) | Migrated | |
|---|---|---|---|
| Tool definition tokens | 85 | 85 | 400 (134 for the tool, 266 for handles.read and jobs.get) |
| Result for a 60-section report | 14,760 tokens, all at once | 14,760 | 388 (preview and handle), then 547 per 2-chunk page |
Fetches http://169.254.169.254/..., 127.0.0.1, [::1] |
Yes | Yes | Refused |
file: URIs |
Any path | Any path | Off unless enabled, then only under one folder |
| Lines changed | 0 (8-line wrapper) | 79 added, 22 removed |