Client Transports

All I/O in Hyperia Client flows through a Transport object. This page dives deep into every built‑in transport, when to use it, and how to customise behaviour.

classDiagram
    Client <|-- StreamableHttpTransport
    Client <|-- SSETransport
    Client <|-- PythonStdioTransport
    Client <|-- NodeStdioTransport
    Client <|-- UvxStdioTransport
    Client <|-- NpxStdioTransport
    Client <|-- HyperiaTransport
    Client <|-- MCPConfigTransport

Rule of thumb — Let Client() infer the right transport from your input (see table below). Instantiate explicitly only when you need custom flags, env vars, or headers.

---

1 Quick Selection Guide

Scenario	Recommended Transport	Inference Trigger
Remote service	StreamableHttpTransport	http(s):// URL without /sse/
Legacy SSE backend	SSETransport (legacy)	URL containing /sse/
Unit tests / same‑process	HyperiaTransport	Pass server instance
Local Python script	PythonStdioTransport	Path ending .py
Local Node script	NodeStdioTransport	Path ending .js
Packaged Python tool (uvx)	UvxStdioTransport	manual instantiation
Packaged NPM tool (npx)	NpxStdioTransport	manual instantiation
Multi‑server config	MCPConfigTransport	MCPConfig dict / file

Keeping a Client context open re‑uses the connection/sub‑process. Opening & closing many short‑lived contexts will incur startup overhead.

---

2 Network Transports

2.1 Streamable HTTP (recommended)

Class hyperia.client.transports.StreamableHttpTransport Introduced v2.3.0

Feature	Notes
Protocol	HTTP/1.1 with chunked streaming (server push + client uploads)
Bidirectional	✔
TLS	Inherits from httpx – supports custom CA bundles, client certs

from hyperia import Client

async with Client("https://api.example.com/mcp") as c:
    print(await c.ping())

Explicit with headers:

from hyperia.client.transports import StreamableHttpTransport
transport = StreamableHttpTransport(
    url="https://api.example.com/mcp",
    headers={"Authorization": "Bearer $TOKEN"},
    timeout=10,
)
client = Client(transport)

2.2 SSE (legacy)

Class hyperia.client.transports.SSETransport Use only when the backend hasn’t migrated to Streamable HTTP.

client = Client("https://legacy.example.com/sse")

Custom headers follow the same pattern as Streamable HTTP.

---

3 Local Sub‑Process Transports

3.1 Python STDIO

client = Client("mysrv.py")                      # simple

Custom interpreter & env:

from hyperia.client.transports import PythonStdioTransport
transport = PythonStdioTransport(
    script_path="mysrv.py",
    python_cmd="python3.12",
    args=["--port", "stdio"],
    env={"DEBUG": "1"},
)
client = Client(transport)

3.2 Node STDIO

client = Client("server.js")

Or manually specify Node binary:

NodeStdioTransport("server.js", node_cmd="/usr/local/bin/node18")

3.3 Uvx STDIO (experimental)

Run any Python tool without installing into the current env:

from hyperia.client.transports import UvxStdioTransport
client = Client(UvxStdioTransport(tool_name="cloud-analyzer-mcp"))

3.4 Npx STDIO (experimental)

from hyperia.client.transports import NpxStdioTransport
client = Client(NpxStdioTransport(package="mcp-server-package"))

---

4 In‑Memory Transport

Fastest possible path—no network or stdio overhead.

from hyperia import Hyperia, Client
srv = Hyperia("Test")

@srv.tool()
def ping(): return "pong"

async with Client(srv) as c:
    print(await c.call_tool("ping"))

Under the hood: two asyncio queues; latency ≈ microseconds—ideal for unit tests.

---

5 Configuration‑Based Transport

MCPConfigTransport lets a single client reach many servers declared in a JSON/YAML/dict.

cfg = {
  "mcpServers": {
    "weather":  {"url": "https://wx.example.com/mcp"},
    "db":       {"command": "python", "args": ["db_server.py"]},
  }
}
client = Client(cfg)

• One server → no prefixes.

• Many servers → tools/resources auto‑prefixed (weather_get_forecast).

---

6 Timeouts & Retries

Each transport obeys the timeout param passed to Client() and the per‑call timeout. HTTP also supports retries= (powered by httpx.Retry).

client = Client("https://api.example.com/mcp", timeout=5, retries=2)

---

7 Security Considerations

• Always use TLS for remote transports—Streamable HTTP validates certs by default.

• Rotate tokens and prefer short‑lived OAuth access tokens.

• Sub‑process transports inherit caller’s env; remove secrets from env before spawning.

---

8 Troubleshooting

Symptom	Likely Cause	Fix
ClientError: roots timeout	Server not listening or wrong path	Verify URL/path; check firewall
STDIO client hangs at connect	Script never calls mcp.run()	Add runner or use HTTP transport
ValueError: cannot infer transport	Path/URL type unrecognised	Instantiate transport explicitly