HeavenBase MCP / Skill

The HeavenBase philosophy: expose an empty workspace and let the agent figure out the schema, entities, and queries through MCP tools. You write zero entity code.

1. Create and serve an empty workspace

Create a single Python file:

# serve_space.py
import heavenbase as hb

ws = hb.HeavenBase("my-space", preset="debug")

print(ws.to_mcp_json(name="my-space-mcp", profile="agent", transport="http", host="127.0.0.1", port=7001))
ws.serve(name="my-space-mcp", profile="agent", transport="http", host="127.0.0.1", port=7001)

No entities, no fields, no schemas. HeavenBase’s generic MCP tools handle everything dynamically.

2. Run it

python serve_space.py

The server prints the client config and starts listening:

{
  "mcpServers": {
    "my-space-mcp": {
      "transport": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

The example uses Streamable HTTP at /mcp. HeavenBase supports the common MCP transports. Use one transport per server process and connect clients to the matching endpoint:

Transport	Python serve call	Client endpoint
Streamable HTTP	`transport="http"`	`http://127.0.0.1:7001/mcp`
SSE	`transport="sse"`	`http://127.0.0.1:7001/sse`
stdio	`transport="stdio"`	command transport, no URL

In Python, pass the same transport to ws.to_mcp_json(...) and ws.serve(...). For example, use transport="sse" in both calls when an SSE-only client needs /sse.

Workspace MCP servers close over the live workspace object. Keep serve_space.py running while external agents use it. Unlike a persisted Toolkit registry ref, an empty workspace MCP server is a live process that exposes the workspace you created in that script.

3. 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 my-space-mcp 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": {
    "my-space-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

Start a new Claude Code session, run /mcp, and confirm my-space-mcp is connected before asking the agent to inspect the workspace.

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: my-space-mcp
Select Streamable HTTP
URL: http://127.0.0.1:7001/mcp

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

[mcp_servers.my-space-mcp]
url = "http://127.0.0.1:7001/mcp"

CLI:

codex mcp add my-space-mcp --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 my-space-mcp appears with the workspace tools.

Use a project-scoped config when the workspace 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": {
    "my-space-mcp": {
      "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: my-space-mcp
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 my-space-mcp 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: my-space-mcp

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

{
  "servers": {
    "my-space-mcp": {
      "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 my-space-mcp 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": {
    "my-space-mcp": {
      "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 my-space-mcp in your prompt.

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

{
  "mcp": {
    "servers": {
      "my-space-mcp": {
        "url": "http://127.0.0.1:7001/mcp",
        "transport": "streamable-http"
      }
    }
  }
}

Or write the same entry with the CLI:

openclaw config set mcp.servers.my-space-mcp '{"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:
  my-space-mcp:
    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 workspace 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": {
    "my-space-mcp": {
      "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 can point at the running workspace MCP URL:

hb llm chat --mcp http://127.0.0.1:7001/mcp "List the available workspace entities."
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, keep serve_space.py running with Streamable HTTP, then connect with MCPServerStreamableHttp:

pip install openai-agents
python serve_space.py

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

import heavenbase as hb

async with MCPServerStreamableHttp(
    name="my-space-mcp",
    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="WorkspaceAgent",
        instructions="Use the HeavenBase MCP tools to inspect and update the workspace.",
        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, "List the available workspace entities.")
    print(result.final_output)

If your SDK version only exposes MCPServerSse, change both calls in serve_space.py to transport="sse" and connect to http://127.0.0.1:7001/sse.

4. Let the agent work

Your agent discovers the HeavenBase agent MCP profile: define_entity, list_entities, describe_entity, upsert, get, set, count, query, and explain. For a note-only memory surface, expose the smaller memory profile instead:

memory = ws.to_mcp(name="my-memory-mcp", profile="memory")
memory.run("remember", key="repo-context", text="Use conda run -n hvnb for HeavenBase tests.", tags=["setup"])
memory.run("search_memory", text="conda")

The memory profile exposes only remember, recall, search_memory, list_memory, and set_memory. It is the right first tool surface when an agent needs persistent notes but should not create schemas or run generic queries yet. Here’s a real interaction with an empty workspace:

> Create a Product entity with name (ShortText), price (Float), and category (ShortText) fields.

> Add a product: "Ergonomic Keyboard" priced at $89.99 in category "electronics".

> Add a product: "27-inch 4K Monitor" priced at $349.00 in category "electronics".

> Add a product: "Bamboo Desk Organizer" priced at $24.50 in category "office".

> What percentage of products in my store cost less than $100?
> List all products in the electronics category sorted by price ascending.

The agent inspects the available tools, defines entities on the fly, writes data, and runs queries — everything through the same MCP interface.

You never write entity code. The agent defines entities via define_entity, writes rows via upsert, and queries via query. Your only job is keeping the server running.

5. Real-world workflow

From a single empty workspace, an agent can build an entire application:

$ python serve_space.py

# Now in your agent:
> Create a Customer entity with name (ShortText), email (ShortText), signup_date (Timestamp) fields.

> Add a customer: Alice Chen, alice@example.com, signed up on 2026-03-15.
> Add a customer: Bob Martinez, bob@example.com, signed up on 2026-01-10.
> Add a customer: Carol Nguyen, carol@example.com, signed up on 2026-04-01.

> Create an Order entity with customer_id (Identifier), total (Float), status (ShortText) fields.

> Add an order for Alice: order A1, total $129.99, status "shipped".
> Add an order for Bob: order B1, total $45.00, status "delivered".
> Add an order for Carol: order C1, total $299.00, status "pending".

> What is the average order value across all orders?
> Which customers have no orders in the last 30 days?

All data, schema, and queries live in the workspace. Start with preset="debug" for a no-Docker first run, then move to preset="local-lts" when you want the local Postgres, LanceDB, and Elasticsearch stack.

Further Exploration

Related resources:

First MCP — generic MCP math toolkit demo
5-min Workshop: Tasklist Manager — typed entities and field routing
Workspace — workspace lifecycle and configuration
MCP overview — workspace MCP toolkit reference
Backends — SQLite, PostgreSQL, MySQL, and more

Documentation Index

​1. Create and serve an empty workspace

​2. Run it

​3. Connect your agent

​4. Let the agent work

​5. Real-world workflow

​Further Exploration

1. Create and serve an empty workspace

2. Run it

3. Connect your agent

4. Let the agent work

5. Real-world workflow

Further Exploration