Your First Hyperia App

Quickstart

Welcome!  This guide walks you through spinning up your first Hyperia MCP server in a few lines of code. If you haven’t installed the library yet, head back to the Installation page.

---

1 · Create a Hyperia Server

A Hyperia server is simply a Python file that instantiates the Hyperia class and then registers MCP components (tools, resources, prompts…). Create my_server.py:

from hyperia import Hyperia

mcp = Hyperia("My MCP Server")

At this point you have a valid MCP server.

---

2 · Add a Tool

Let’s make it useful by adding a greeting tool. Decorate any function with @mcp.tool() to register it:

from hyperia import Hyperia

mcp = Hyperia("My MCP Server")

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

---

3 · Test Locally with an In‑Process Client

Hyperia includes an async client you can point at any server instance. Append this to my_server.py or place it in a separate script:

import asyncio
from hyperia import Hyperia, Client

mcp = Hyperia("My MCP Server")

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

client = Client(mcp)  # in‑process connection

async def call_tool(name: str):
    async with client:
        result = await client.call_tool("greet", {"name": name})
        print(result)

asyncio.run(call_tool("Ford"))

Notes • Client is asynchronous, so we use asyncio.run. • Entering the client context (async with …) lets you make multiple calls on the same connection.

---

4 · Run the Server as a Script

Add a __main__ guard so the server can be launched with plain Python:

from hyperia import Hyperia

mcp = Hyperia("My MCP Server")

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

if __name__ == "__main__":
    mcp.run()  # uses the default stdio transport

Then start it:

python my_server.py

Why the if __name__ == "__main__": block? Including it ensures your server behaves consistently across shells, IDEs, and container runners—even when Hyperia’s CLI isn’t used.

---

5 · Interact from Another Process

Create a separate file my_client.py to demonstrate talking to a running server via stdio transport:

import asyncio
from hyperia import Client

client = Client("my_server.py")  # path to script

async def call_tool(name: str):
    async with client:
        result = await client.call_tool("greet", {"name": name})
        print(result)

asyncio.run(call_tool("Ford"))

Hyperia recognizes the .py file as an MCP server and spawns it with python my_server.py under the hood.

---

6 · Using the Hyperia CLI

Prefer not to manage processes yourself? The CLI can run the server for you and keep it alive until terminated:

hyperia run my_server.py:mcp

• my_server.py is the module path.

• mcp specifies the server object. If omitted, Hyperia searches for mcp, app, or server automatically.

The CLI ignores any __main__ guard and uses the faster internal runner. Additional transport and deployment options are covered in the Server Configuration guide.