Deployment & Hosting

Run your Hyperia server locally or in production using STDIO, Streamable HTTP, or (legacy) SSE transports.

Hyperia servers can be started:

• In‑code via mcp.run() / mcp.run_async().

• From the CLI with hyperia run or hyperia dev.

• Inside ASGI stacks (covered in Advanced ASGI Integration).

This guide focuses on the built‑in runner and CLI.

---

1 · run() – the one‑liner

Place the call in a __main__ guard so importing the module doesn’t auto‑start the server:

# my_server.py
from hyperia import Hyperia

mcp = Hyperia("MyServer")

@mcp.tool()
def hello(name: str):
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()          # defaults to stdio transport

Run:

python my_server.py

run() arguments:

mcp.run(
    transport="streamable-http",   # "stdio" (default) | "streamable-http" | "sse" (deprecated)
    host="127.0.0.1",
    port=8000,
    path="/mcp",                  # HTTP/SSE path
    log_level="info",
)

Async flavour

If your script is already async, use await mcp.run_async(...).

async def main():
    await mcp.run_async(transport="streamable-http")

Calling blocking run() inside an event loop will raise an error.

---

2 · Hyperia CLI

The CLI bypasses the __main__ guard and hunts for an object named mcp, server, or app.

hyperia run my_server.py

Override transport on the fly:

hyperia run my_server.py --transport streamable-http --port 9000

Development mode (auto‑reload + Inspector):

hyperia dev my_server.py

See hyperia --help for all flags.

---

3 · Choosing a Transport

Transport	Ideal For	Pros	Cons
STDIO (default)	Local tools, IDEs (Cursor, Claude Desktop)	Zero config; client spawns per‑session	Server code runs on client machine (security); not network‑shareable
Streamable HTTP	Web/API deployments, containers, microservices	Stateless option, efficient streaming, easily load‑balanced	Requires open port + reverse proxy in prod
SSE (legacy)	Older setups reliant on EventSource	Simple; existing infra	Deprecated – prefer Streamable HTTP

STDIO example (explicit)

if __name__ == "__main__":
    mcp.run(transport="stdio")

Clients typically launch the server themselves; no extra config needed.

Streamable HTTP example

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=4200,
        path="/mcp",
        log_level="debug",
    )

Starts Uvicorn under the hood. Deploy behind nginx/Traefik or a cloud LB.

SSE (deprecated)

mcp.run(transport="sse", host="127.0.0.1", port=4200, path="/sse")

Use only for backward compatibility; new projects should migrate.

---

4 · Custom Routes

Need a quick health‑check? Add routes without a full ASGI framework:

from hyperia import Hyperia
from starlette.responses import PlainTextResponse

mcp = Hyperia("Srv")

@mcp.custom_route("/health", methods=["GET"])
async def health(_):
    return PlainTextResponse("OK")

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

For complex web apps, mount the Hyperia ASGI app inside FastAPI/Starlette instead.

---

5 · Deployment Tips

• Docker – pip install hyperia && python my_server.py --transport streamable-http --host 0.0.0.0 in CMD.

• Kubernetes – expose port, add readiness probe hitting /health.

• Serverless – wrap the ASGI app in an adapter (AWS Lambda + Lambda‑Powertools, GCP Cloud Run, etc.).

• TLS/Certs – terminate at ingress/proxy; Hyperia’s built‑in Uvicorn runner is HTTP only.

---

6 · Recap

run() / run_async() for code‑driven starts, hyperia run for CLI flexibility. Streamable HTTP is the recommended production transport; STDIO remains perfect for local tool execution.