Hyperia Protocol Overview

Welcome to Hyperia Protocol

Hyperia is the fast, Pythonic way to build Model Context Protocol (MCP) servers and clients.

MCP is a new, standardized method for supplying context, data, and tools to large‑language models. Hyperia removes the boilerplate: create tools, expose resources, define prompts, and more with clean, readable Python.

from hyperia import Hyperia

mcp = Hyperia("Demo 🚀")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

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

---

Hyperia Protocol & the Official MCP SDK

Two pillars, one ecosystem.

	Hyperia Protocol	Official MCP SDK
Maintainer	Hyperia Labs Inc.	MCP Foundation (spec reference impl)
Primary Goal	Developer ergonomics – rapid, high‑level binding of existing code, APIs, and data into MCP.	Specification fidelity – low‑level, one‑to‑one mapping of the core MCP wire format.
Abstraction Level	High: decorators, automatic route mapping, generators (OpenAPI, FastAPI, SQLAlchemy, etc.).	Low: you implement message handlers, transports, serialization manually.
Performance Focus	Async, zero‑copy in‑process calls; optional HTTP layer.	Reference‑grade correctness, not optimised.
Extra Capabilities:	Progress events
	Chunk streaming
	Auto‑retry/back‑off
	Codecs registry
	Proxy & composition helpers
	ASGI/Starlette adapters	Minimal extras (kept generic to remain specification neutral).
Ideal Users	Product teams, ML engineers, plugin authors needing to expose back‑ends to LLMs fast.	Researchers, alt‑language ports, edge cases needing full control.
Inter‑operability	100% wire‑compatible – Hyperia servers & clients speak the exact MCP frames defined by the spec.	N/A

---

How They Work Together

• Hyperia ≈ "Rails", Official SDK ≈ "C library". Both compile to the same MCP bytes.

• Hyperia actually contributes upstream: several transport & context improvements first landed here, then merged into SDK v1.6.

• You can mix: implement a custom component in raw SDK and mount it into a Hyperia server, or proxy an SDK server behind Hyperia’s richer transports.

graph LR
    subgraph Raw SDK Server
        A[tools/call handler]<--MCP-->B(Hyperia Proxy)
    end
    B-->C(Client Apps)

---

Migration Path

Scenario	Recommendation
New project, wants speed	Start with Hyperia; drop to SDK only for exotic needs.
Existing SDK 1.x server	pip install hyperia → from hyperia import Hyperia as mcp
Swap imports or proxy via Hyperia.as_proxy(sdk_server) to gain progress/logging instantly.
Contributing to the spec	Prototype in Hyperia (faster dev cycle), then port minimal patch to SDK.

---

Version Sync Table

MCP Spec Date	Official SDK	Hyperia Tag	Notes
2025‑03‑26 (latest)	1.9.0	2.4.0	OAuth 2.1 auth, chunk streaming
2024‑11‑05	1.7.1	2.2.3	Wildcard resource templates
2024‑07‑18	1.6.0	2.0.0	Initial sync; Hyperia born

Hyperia tracks spec releases within 72 h; patch versions follow semver.

---

Choosing One (or Both)

If you crave control ➜ official SDK. If you crave velocity ➜ Hyperia. Most teams end up using both: Hyperia for day‑to‑day features, raw SDK for critical, performance‑tuned modules.

---

llms.txt

This documentation is also distributed in llms.txt format—a lightweight Markdown profile that LLMs can ingest directly.

• llms.txt – a sitemap of every page.

• llms-full.txt – the complete docs in a single file (may exceed some model context windows).