First MCP - HeavenBase

MCP servers ensure you never reinvent the wheel. We want you to never reinstall the wheels either.

Most MCP servers define functions and then start a process. HeavenBase adds registry persistence: the toolkit’s source code, signatures, docstrings, and revision history are captured in a Capsule registry. Register once, then serve the toolkit from a small script or the CLI after the original .py file is gone.

1. Demo: Create a Math Toolkit

Define plain functions and pass them as a list. HeavenBase uses each function’s __name__ as the tool name:

# 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

if __name__ == "__main__":
    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, pass a dict such as {"add": add, "mul": mul} instead. HeavenBase captures source code, type annotations, and import references automatically. The namespace="quickstart" argument groups this demo Toolkit under the quickstart registry prefix so hb mcp list and serve commands can target quickstart.math-tools. 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 now live in the registry. That persistence is the important distinction. After registration, serving can happen from another script, after a reboot, or from another machine when the registry database is shared.

3. Load and Serve from Anywhere

With the toolkit persisted, loading and serving require no function definitions and no imports from the original module:

# 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:

Transport	Serve command	Client endpoint
Streamable HTTP	`hb mcp serve quickstart.math-tools --transport http`	`http://127.0.0.1:7001/mcp`
SSE	`hb mcp serve quickstart.math-tools --transport sse`	`http://127.0.0.1:7001/sse`
stdio	`hb mcp stdio quickstart.math-tools`	command 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. HeavenBase’s registry decouples creation from serving, so the same registered Toolkit can be served from any process that can read the registry DB. 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

The call command should print 5; mcp-json should print the same HTTP config shown above.

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.

Codex supports three methods: CLI, config file, and GUI (Codex App or IDE extension).GUI (Codex App): Settings > MCP servers > + Add server, then enter:

Name: math-tools
Select Streamable HTTP
URL: http://127.0.0.1:7001/mcp

Config file (~/.codex/config.toml):

[mcp_servers.math-tools]
url = "http://127.0.0.1:7001/mcp"

CLI:

codex mcp add math-tools --url http://127.0.0.1:7001/mcp
codex mcp list

If your Codex build does not show HTTP MCP servers after adding them, enable the experimental_use_rmcp_client feature in ~/.codex/config.toml:

[features]
experimental_use_rmcp_client = true

Start a new Codex session, or run /mcp in the TUI, and confirm math-tools appears with its discovered tools.

Use a project-scoped config when the server belongs to one repo, or a global config when you want it everywhere:

Project: .cursor/mcp.json
Global: ~/.cursor/mcp.json

Paste this config:

{
  "mcpServers": {
    "math-tools": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

You can also open Cursor Settings > Features > MCP > Add new global MCP server, then enter:

Name: math-tools
Type: http
URL: http://127.0.0.1:7001/mcp

Reload Cursor or open a new chat, then check the MCP settings panel to confirm math-tools is enabled.

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS), run MCP: Add Server, select HTTP, then enter:

URL: http://127.0.0.1:7001/mcp
Name: math-tools

For a workspace-scoped setup, add .vscode/mcp.json. VS Code uses the servers key, not mcpServers:

{
  "servers": {
    "math-tools": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

Reload the VS Code window or run MCP: List Servers from the Command Palette, then confirm math-tools is running.

Add the remote MCP server to your project opencode.json / opencode.jsonc, or to the global config at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "math-tools": {
      "type": "remote",
      "url": "http://127.0.0.1:7001/mcp",
      "enabled": true
    }
  }
}

On Windows, use %APPDATA%\opencode\config.jsonc for the global config. Restart OpenCode or run opencode mcp list to confirm the server is available, then refer to math-tools in your prompt.

Add the server under mcp.servers in ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "math-tools": {
        "url": "http://127.0.0.1:7001/mcp",
        "transport": "streamable-http"
      }
    }
  }
}

Or write the same entry with the CLI:

openclaw config set mcp.servers.math-tools '{"url":"http://127.0.0.1:7001/mcp","transport":"streamable-http"}'
openclaw mcp list

OpenClaw hot-applies most MCP config changes. Start a new agent session if an existing session already loaded its tools.

Add the HTTP server to ~/.hermes/config.yaml:

mcp_servers:
  math-tools:
    url: "http://127.0.0.1:7001/mcp"
    enabled: true

Reload or restart Hermes after saving the file, then ask it to list available MCP tools and confirm the arithmetic tools are present.

In LM Studio, open the Program/Developer panel, choose Install > Edit mcp.json, and add the server. LM Studio follows Cursor-style mcp.json notation:

{
  "mcpServers": {
    "math-tools": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

Save the file, enable the server if LM Studio shows a toggle, and start a new chat with tool use enabled.

HeavenBase has its own LLM chat/session interface and you can use --mcp to connect to the MCP server directly from the registry:

hb llm chat --mcp quickstart.math-tools "What's 42 * 73?"
hb llm session --mcp quickstart.math-tools

You can also point HeavenBase at the running HTTP MCP endpoint:

hb llm session --mcp http://127.0.0.1:7001/mcp

Inside an interactive session, add another MCP source with /mcp SOURCE.

Install the SDK, start the HeavenBase server with Streamable HTTP, then connect with MCPServerStreamableHttp:

pip install openai-agents
hb mcp serve quickstart.math-tools --transport http

from agents import Agent, ModelSettings, OpenAIChatCompletionsModel, Runner
from agents.mcp import MCPServerStreamableHttp

import heavenbase as hb

async with MCPServerStreamableHttp(
    name="math-tools",
    params={"url": "http://127.0.0.1:7001/mcp"},
    cache_tools_list=True,
) as server:
    llm = hb.LLM(preset="chat")
    model_args = llm.to_args()
    model_name = model_args.pop("model")

    agent = Agent(
        name="MathAgent",
        instructions="Use the MCP math tools when they help.",
        model=OpenAIChatCompletionsModel(
            model=model_name,
            openai_client=llm.to_aclient(),
        ),
        model_settings=ModelSettings(**model_args),
        mcp_servers=[server],
        mcp_config={"include_server_in_tool_names": False},
    )

    result = await Runner.run(agent, "What's 42 * 73?")
    print(result.final_output)

If your SDK version only exposes MCPServerSse, start HeavenBase with hb mcp serve quickstart.math-tools --transport sse and connect to http://127.0.0.1:7001/sse.

6. Try It Out

Once connected, ask your agent to use the math tools:

> What's 42 * 73?
> Compute the first 15 Fibonacci numbers.
> What is the 63rd Fibonacci number modulo 10000?
> 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:

HeavenBase MCP - expose a workspace over MCP, no entity code to write
30min Developer Workshop: Tasklist Manager - build Sublinear, an agentic tasklist manager
Toolkits - Toolkit architecture, MCP serving, and import
Capsules - persist any Python function
MCP toolkit reference - full tool list and serving options

​1. Demo: Create a Math Toolkit

​2. Run Once to Persist

​3. Load and Serve from Anywhere

​4. Serve Directly from the CLI

​5. Connect Your Agent

​6. Try It Out

​Further Exploration

1. Demo: Create a Math Toolkit

2. Run Once to Persist

3. Load and Serve from Anywhere

4. Serve Directly from the CLI

5. Connect Your Agent

6. Try It Out

Further Exploration