First MCP

A tool without an owner is just a function looking for trouble.

HeavenBase can turn ordinary Python functions into MCP tools, but the important boundary is ownership. A registered Toolkit and every Capsule it references belong to one explicit application workspace. That workspace keeps creation, inspection, serving, and deletion pointed at the same durable state. There is no process-global Toolkit database, and another process must open the same registered workspace before it can load the tools.

1. Motivation

A global registry makes short demos look convenient until two applications register math-tools, one application deletes another’s revision, or a server silently opens the wrong database. HeavenBase makes the workspace explicit instead:

toolkit.register(ws=workspace)
loaded = hb.Toolkit.load(
    name="math-tools", namespace="quickstart", version="1", ws=workspace
)

The workspace owns the Toolkit row, the referenced Capsule rows, and their backend lifecycle. Your Python functions remain normal functions; HeavenBase adds durable identity and an MCP adapter around them.

2. Create a Workspace-Owned Toolkit

Create math_tools.py:

import heavenbase as hb


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


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


workspace = hb.HeavenBase("math-demo", preset="debug")
toolkit = hb.Toolkit(
    "math-tools",
    {"add": add, "multiply": multiply},
    namespace="quickstart",
    version="1",
    description="Small arithmetic tools",
)
toolkit.register(
    ws=workspace,
    overwrite=True,
    reason="initial quickstart tools",
)

Run it once:

python math_tools.py

Registration captures callable source, signatures, annotations, imports, serializers, and Toolkit metadata into workspace-owned rows. The stable reference is quickstart/math-tools:1.

Capsule restoration executes captured Python. Register and load only code you trust, and treat access to the owning workspace as code-execution authority.

3. Load and Serve from Another Process

The serving process opens the same workspace explicitly:

import heavenbase as hb


workspace = hb.HeavenBase.load("math-demo")
toolkit = hb.Toolkit.load(
    name="math-tools",
    namespace="quickstart",
    version="1",
    ws=workspace,
)

print(toolkit.to_mcp_json())
toolkit.serve(wait=True)

You can run this code after deleting math_tools.py because the workspace retains the captured Capsules. The process still needs the same HeavenBase home, workspace registration, and artifact store; persistence is workspace-scoped, not ambient or magically cross-machine. The server listens at http://127.0.0.1:7001/mcp by default. Use one transport per process:

Transport	Command	Client endpoint
Streamable HTTP	`hb mcp serve quickstart.math-tools --workspace math-demo --transport http`	`http://127.0.0.1:7001/mcp`
SSE	`hb mcp serve quickstart.math-tools --workspace math-demo --transport sse`	`http://127.0.0.1:7001/sse`
stdio	`hb mcp stdio quickstart.math-tools --workspace math-demo`	Command transport

4. Inspect and Serve with the CLI

Every Toolkit command accepts the owning workspace:

hb mcp list --workspace math-demo
hb mcp tools quickstart.math-tools --workspace math-demo
hb mcp call quickstart.math-tools add \
  --workspace math-demo \
  --args '{"left": 2, "right": 3}'
hb mcp mcp-json quickstart.math-tools --workspace math-demo

The call prints 5. Start the HTTP server without a serving script:

hb mcp serve quickstart.math-tools --workspace math-demo

The same ownership rule applies in Python:

rows = hb.Toolkit.list(ws=workspace, namespace="quickstart")
hb.Toolkit.delete(rows[0]["object_id"], ws=workspace)

Deleting a Toolkit tombstones its row by default. Dropping the workspace is the broader lifecycle action because it also owns the associated data and Capsule rows.

5. Connect a Client

Keep the server running, then configure one client for its Streamable HTTP URL.

Claude Code
Codex
VS Code

Add and verify the server:

claude mcp add --transport http math-tools http://127.0.0.1:7001/mcp
claude mcp list

Start a new session and run /mcp to inspect the discovered tools.

Add this table to ~/.codex/config.toml or a trusted project’s .codex/config.toml:

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

Restart the app or extension after saving, or run /mcp in the Codex CLI to inspect the server.

Create .vscode/mcp.json:

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

Run MCP: List Servers from the Command Palette to inspect or restart it.

For another client, start with the JSON emitted by hb mcp mcp-json quickstart.math-tools --workspace math-demo and adapt only the client-specific wrapper key.

6. Try It Out

Ask the connected agent:

Use the math-tools MCP server to calculate 42 * 73, then add 19.

The agent discovers multiply and add from their signatures and docstrings, calls them, and should return 3085.

Summary

Concrete Toolkits and their referenced Capsules belong to an explicit workspace.
Registration may outlive the source file, but loading still requires the same workspace authority.
Python and CLI operations use the same workspace-owned rows.
Workspace-bound tools are trusted executable code, not inert data.

Further Exploration

Related resources:

HeavenBase MCP - Expose one live workspace directly
Toolkits - Understand Toolkit identity and profiles
Capsules - Inspect callable capture and restoration
MCP Toolkit Reference - Review CLI and serving contracts
Claude Code MCP - Configure Claude Code
Codex MCP - Configure Codex clients
VS Code MCP - Configure VS Code

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Create a Workspace-Owned Toolkit

3. Load and Serve from Another Process

4. Inspect and Serve with the CLI

5. Connect a Client

6. Try It Out

Summary

Further Exploration

​1. Motivation

​2. Create a Workspace-Owned Toolkit

​3. Load and Serve from Another Process

​4. Inspect and Serve with the CLI

​5. Connect a Client

​6. Try It Out

​Summary

​Further Exploration

1. Motivation

2. Create a Workspace-Owned Toolkit

3. Load and Serve from Another Process

4. Inspect and Serve with the CLI

5. Connect a Client

6. Try It Out

Summary

Further Exploration