Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

Every MCP server defines functions and starts a server. HeavenBase adds one step that changes the game: persistence. Your toolkit — source code, signatures, docstrings, revision history — is captured and stored in a registry. Register once, serve from any script, reload after reboots, share across teams. The original .py file becomes optional.
Persistence is the difference between “start the server every time” and “the server is always available.” HeavenBase’s registry is a hidden workspace that stores every toolkit and its revision history.

​
1. Create a math toolkit

Define plain functions and pass them as a list — HeavenBase reads each function’s name automatically: 
# math_tools.py
import heavenbase as hb


def add(left: int, right: int) -> int:
    """Add two numbers."""
    return left + right


def sub(left: int, right: int) -> int:
    """Subtract right from left."""
    return left - right


def mul(left: int, right: int) -> int:
    """Multiply two numbers."""
    return left * right


def div(left: int, right: int) -> float:
    """Divide left by right."""
    return left / right


def mod(left: int, right: int) -> int:
    """Return left modulo right."""
    return left % right


def fibonacci(n: int) -> list[int]:
    """Return the first n Fibonacci numbers."""
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result


toolkit = hb.Toolkit(
    "math-tools",
    [add, sub, mul, div, mod, fibonacci],
    description="Basic arithmetic and sequence operations",
    namespace="quickstart",
    version="1",
)

toolkit.register(overwrite=True, reason="initial quickstart math tools")
Passing a list of functions is the simplest form — the function __name__ becomes the tool name and the docstring becomes the tool description. For custom names use {"alias": fn} instead. HeavenBase captures source code, type annotations, and import references automatically. The reason value is a human-readable registry revision note, useful when you inspect Toolkit history later.

​
2. Run once to persist

python math_tools.py
At this point the toolkit is checksummed and stored in the registry. You can delete math_tools.py — the functions live in the registry now.

​
3. Load and serve from anywhere

With the toolkit persisted, loading and serving needs no function definitions, no imports of the original modules: 
# serve_math.py
import heavenbase as hb

loaded = hb.Toolkit.load(name="math-tools", namespace="quickstart", version="1")
print(loaded.to_mcp_json())
loaded.serve(wait=True)

python serve_math.py
The server prints the MCP config and listens at http://127.0.0.1:7001/mcp: 
{
  "mcpServers": {
    "math-tools": {
      "transport": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}
HeavenBase supports the common MCP transports. Use one transport per server process and connect clients to the matching endpoint:
TransportServe commandClient endpoint
Streamable HTTPhb mcp serve quickstart.math-tools --transport httphttp://127.0.0.1:7001/mcp
SSEhb mcp serve quickstart.math-tools --transport ssehttp://127.0.0.1:7001/sse
stdiohb mcp stdio quickstart.math-toolscommand transport, no URL
In Python, pass the same transport to loaded.to_mcp_json(transport="sse") and loaded.serve(transport="sse", wait=True) when an SSE-only client needs /sse.
Splitting registration and serving into two scripts is deliberate — it shows that the toolkit outlives the script that created it. With FastMCP and other frameworks, defining functions and serving is a single step; every restart re-runs the definition code. HeavenBase’s registry decouples creation from serving: register once, serve from any process, reload after machine reboots, share the registry DB across a team. You can combine both steps in one file when convenience matters more.

​
4. Serve directly from the CLI

Skip the server script entirely — the CLI loads and serves any persisted toolkit: 
hb mcp serve quickstart.math-tools
List, inspect, and call tools without writing a line of server code: 
hb mcp list
hb mcp tools quickstart.math-tools
hb mcp call quickstart.math-tools add --args '{"left": 2, "right": 3}'
hb mcp mcp-json quickstart.math-tools

​
5. Connect your agent

Add the server to your preferred coding agent:
Add the HTTP server with the Claude Code CLI:
claude mcp add --transport http math-tools http://127.0.0.1:7001/mcp
claude mcp list
Claude Code stores local-scoped MCP servers in ~/.claude.json. For a repo-shared setup, run the same command with --scope project from the project root, or create .mcp.json:
{
  "mcpServers": {
    "math-tools": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}
Start a new Claude Code session, run /mcp, and confirm math-tools is connected before asking the agent to use the arithmetic tools.

​
6. Try it out

Once connected, ask your agent to use the math tools: 
> What's 42 * 73?
> Compute the first 15 Fibonacci numbers.
> Is 97 a prime number? (use mod to check divisibility)
> Calculate (85 + 37) * 12 / 4
The agent discovers each tool’s name, description, and parameter schema through MCP, then calls them as needed.
Because the toolkit is persisted, you can stop the server, reboot, and resume with hb mcp serve quickstart.math-tools — no script, no redefinition, no loss.

​
Further Exploration

Next steps: