ann_router.mcp_server module

MCP server — the agent-tool door (optional [mcp] extra), via fastapi-mcp.

The fifth surface (paired with the skills/ann-router skill) lets an AI agent call the router as Model-Context-Protocol tools. Rather than hand -writing a parallel set of @server.tool() wrappers (the previous design, which duplicated every endpoint’s parameter list and docstring against ann_router.api), this module mounts fastapi-mcp on a copy of that same FastAPI app: the three REST operations already tagged with an explicit operation_id there (route/capabilities/bench) become the three MCP tools here, automatically, with the same request/response schema. Rename or extend a route in api.py and this door follows without a second edit.

This is an architectural change from the pre-fastapi-mcp version: MCP is now served over Streamable HTTP (mounted at /mcp on a running app), not stdio — a stdio subprocess client (spawn-and-talk-over-stdin/stdout) is not what fastapi-mcp offers; an HTTP-based MCP client pointed at the running server’s /mcp endpoint is. The upside: the exact same three tools are also just REST endpoints an agent (or a human with curl) can hit directly.

Run it with:

pip install 'ann-router[mcp]'
uvicorn ann_router.mcp_server:app --port 8019   # or: python -m ann_router.mcp_server

MCP endpoint: http://127.0.0.1:8019/mcp. Runs on a different port from ann_router.api’s 8018 by default so both doors can run side by side.

Consumes: fastapi-mcp (optional, pulls in fastapi/mcp), ann_router.api. Produces: app (the ASGI application), build_server().

Author: Warith Harchaoui <warith.harchaoui@deraison.ai>

ann_router.mcp_server.build_server(app)

Mount the MCP server (route/capabilities/bench tools) onto app.

Parameters:

app (fastapi.FastAPI) – The app to mount onto — typically a fresh ann_router.api.create_app() instance, so this module’s app stays independent of ann_router.api’s own module-level one.

Returns:

The mounted server descriptor (.name defaults to app.title).

Return type:

fastapi_mcp.FastApiMCP

Examples

>>> from ann_router.api import create_app
>>> mcp = build_server(create_app())
>>> mcp.name
'ann-router'

ann_router.mcp_server.main()

Run the MCP-mounted app over HTTP (the python -m ann_router.mcp_server path).

Return type:

None