FastAPI → Hyperia Bridge

Transform any FastAPI application into a live Hyperia MCP server with a single call—unlocking LLM‑ready tools and resources while preserving your existing Python business logic.

Prerequisite Install FastAPI & an ASGI runtime: pip install fastapi uvicorn[standard].

1 Hello‑World Conversion

from fastapi import FastAPI
from hyperia import Hyperia

api = FastAPI()

@api.get("/ping")
def ping():
    return {"pong": True}

mcp = Hyperia.from_fastapi(app=api, name="PingAPI")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=9100)

Now any Hyperia client (or Claude Desktop) can read_resource("resource://ping").

2 How the Converter Works

  1. Inspects the FastAPI app’s router (app.openapi() behind the scenes).

  2. Applies route‑mapping rules (see §3).

  3. Builds wrappers that:

    • Extract path/query/body args from the MCP call.

    • Invoke the FastAPI dependency graph (including Depends, auth, middle‑ ware).

    • Serialise the Starlette Response → MCP contents.

  4. Registers the new callable with the Hyperia server.

Because we bypass the network, calls execute in‑process with the same Python interpreter—zero HTTP overhead.

3 Default Route Mapping

FastAPI Decorator
Example
Hyperia Component
Name / URI result

@api.get("/stats")

no params

Resource

resource://stats

@api.get("/users/{id}")

has path param

ResourceTemplate

users://{id}

any non‑GET (post/put/patch/delete)

@api.post("/users")

Tool

createUser (from op id or path)

Customise with route_maps (same structure as OpenAPI integration):

from hyperia.server.openapi import RouteMap, RouteType
maps = [RouteMap(methods=["GET"], pattern=r"^/export/.*", route_type=RouteType.TOOL)]

mcp = Hyperia.from_fastapi(app, route_maps=maps)

all_routes_as_tools=True forces everything to be a Tool—nice for agent back‑ends.

4 Timeout & Concurrency Control

mcp = Hyperia.from_fastapi(app, timeout=4.0, max_concurrency=50)

  • timeout – per‑request ceiling (seconds) for tool/resource execution.

  • max_concurrency – semaphore protecting the underlying FastAPI app when hit via MCP (does not affect external HTTP calls to the same FastAPI app).

5 Advanced Examples

5.1 CRUD Service with Pydantic Models

from pydantic import BaseModel
from fastapi import FastAPI, HTTPException
from hyperia import Hyperia

class Item(BaseModel): name: str; price: float
api = FastAPI(); db: dict[int, Item] = {}

@api.get("/items", response_model=list[Item])
def list_items(): return list(db.values())

@api.post("/items", response_model=Item, status_code=201)
def new(item: Item):
    idx = len(db)+1; db[idx] = item; return item

@api.get("/items/{idx}")
def get(idx: int):
    if idx not in db: raise HTTPException(404)
    return db[idx]

mcp = Hyperia.from_fastapi(api, name="Shop")

Generated components:

  • Tool new (calls POST /items)

  • Resource items (GET /items)

  • Template items://{idx} (GET /items/{idx})

5.2 Streaming Responses

FastAPI StreamingResponse → Hyperia chunked TextContent. Supports SSE or incremental JSON.

5.3 Auth Propagation

If your FastAPI endpoints use Depends(get_current_user), they still work—Hyperia just runs the dependency call chain.

For agent scenarios supply a dummy user via DependencyOverrides before wrapping:

api.dependency_overrides[get_current_user] = lambda: User(id=1, name="agent")

6 Why Use FastAPI→Hyperia Instead of OpenAPI→Hyperia?

Criteria
FastAPI wrapper
OpenAPI wrapper

Same‑process calls

✔

✖ (HTTP)

Re‑use FastAPI dependencies & state

✔

✖

No existing spec file

✔

✖

You only have OpenAPI description

✖

✔

Need multi‑language SDKs

✖

✔ (just use spec)

You can even combine: expose some endpoints through HTTP (OpenAPI) and mount a FastAPI‑wrapped MCP for internal operations.

7 Limitations & Caveats

  • FastAPI middlewares that modify the raw ASGI send/receive flow (e.g. WebSocket) are ignored for MCP calls.

  • Background tasks run inside the MCP event‑loop—monitor memory.

  • Proprietary Response classes (FileResponse, RedirectResponse) map to simple TextContent with their .body string or URL.

  • Multipart form file uploads require the client to supply base64 blobs; binary passthrough coming in v2.6.

8 Troubleshooting

Symptom
Cause
Fix

RuntimeError: FastAPI not installed

dependency missing

pip install fastapi

422 errors when tool called

Validation failed on pydantic model

check arg names & types; they must match FastAPI signature

Tool returns null

Endpoint returned Response(status_code=204)

Upgrade to v2.5 (maps 204 → empty list)

PreviousOpenAPI ⇢ Hyperia Server

Last updated