> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# First MCP

> Create a demo math toolkit, persist it in HeavenBase's Capsule registry, and serve it over MCP from anywhere.

<Note>
  *MCP servers ensure you never reinvent the wheel. We want you to never reinstall the wheels either.*
</Note>

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.

<br />

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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")
```

<Info>
  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.
</Info>

<br />

## 2. Run Once to Persist

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 3. Load and Serve from Anywhere

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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)
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
python serve_math.py
```

The server prints the MCP config and listens at `http://127.0.0.1:7001/mcp`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

<Note>
  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.
</Note>

<br />

## 4. Serve Directly from the CLI

Skip the server script entirely. The CLI loads and serves any persisted toolkit:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb mcp serve quickstart.math-tools
```

List, inspect, and call tools without writing a line of server code:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 5. Connect Your Agent

Add the server to your preferred coding agent:

<Tabs>
  <Tab title="Claude Code">
    Add the HTTP server with the Claude Code CLI:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.
  </Tab>

  <Tab title="Codex">
    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`):

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    [mcp_servers.math-tools]
    url = "http://127.0.0.1:7001/mcp"
    ```

    CLI:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    codex mcp add math-tools --url http://127.0.0.1:7001/mcp
    codex mcp list
    ```

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

      ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
      [features]
      experimental_use_rmcp_client = true
      ```
    </Note>

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

  <Tab title="Cursor">
    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:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.
  </Tab>

  <Tab title="VS Code / Copilot">
    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`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.
  </Tab>

  <Tab title="OpenCode">
    Add the remote MCP server to your project `opencode.json` / `opencode.jsonc`, or to the global config at `~/.config/opencode/opencode.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "$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.
  </Tab>

  <Tab title="OpenClaw">
    Add the server under `mcp.servers` in `~/.openclaw/openclaw.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcp": {
        "servers": {
          "math-tools": {
            "url": "http://127.0.0.1:7001/mcp",
            "transport": "streamable-http"
          }
        }
      }
    }
    ```

    Or write the same entry with the CLI:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Tab>

  <Tab title="Hermes">
    Add the HTTP server to `~/.hermes/config.yaml`:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Tab>

  <Tab title="LM Studio">
    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:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.
  </Tab>

  <Tab title="HeavenBase">
    HeavenBase has its own LLM chat/session interface and you can use `--mcp` to connect to the MCP server directly from the registry:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    hb llm session --mcp http://127.0.0.1:7001/mcp
    ```

    Inside an interactive session, add another MCP source with `/mcp SOURCE`.
  </Tab>

  <Tab title="OpenAI Agents SDK">
    Install the SDK, start the HeavenBase server with Streamable HTTP, then connect with `MCPServerStreamableHttp`:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pip install openai-agents
    hb mcp serve quickstart.math-tools --transport http
    ```

    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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`.
  </Tab>
</Tabs>

<br />

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

<Note>
  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.
</Note>

<br />

## Further Exploration

<Tip>
  **Next steps:**

  * [HeavenBase MCP](/quickstart/heavenbase-mcp) - expose a workspace over MCP, no entity code to write
  * [30min Developer Workshop: Tasklist Manager](/quickstart/sublinear-workshop) - build Sublinear, an agentic tasklist manager
  * [Toolkits](/features/toolkits) - Toolkit architecture, MCP serving, and import
  * [Capsules](/features/capsules) - persist any Python function
  * [MCP toolkit reference](/reference/mcp-toolkit) - full tool list and serving options
</Tip>

<br />