HeavenBase MCP - HeavenBase

The best canvas is an empty one.

In this tutorial, we create an empty HeavenBase workspace and expose it as an MCP server. This allows any agent using HeavenBase MCP as a data surface and structured memory service. The agents decide how to store their observation, what to store, and how to query it. The MCP server handles the rest. At the end of the tutorial, we’ll run a toy e-commerce scenario. The agent defines Product, Customer, and Order entities on the fly, then maintain the database with daily operations like adding products, registering customers, and recording orders. Finally, the agent answers analytical questions about the business, such as “What percentage of products cost less than $100?” and “What should I recommend to Alice based on her order history?“

1. Create an Empty Workspace

Create a single Python file:

# serve_space.py
import heavenbase as hb

# If you've already run this tutorial once, this drops the existing workspace so you can start fresh.
# Remove this line if you want the workspace to persist across server restarts.
hb.HeavenBase("my-space", preset="debug").drop()

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.

hb.HeavenBase("my-space", preset="debug").drop() clears the demo workspace before the server starts. Use this reset line for repeatable tutorials, and remove it when you want the workspace data to persist across server restarts.

The preset argument controls the backend configuration. The debug preset uses SQLite and in-memory stores for a lightweight, no-Docker setup. The local-lts preset uses local Postgres, LanceDB, and Elasticsearch for a more robust setup that still runs on your machine. Both presets support the full MCP toolset, with the debug preset focusing on ease of use and the local stack being more performant for larger data. The profile argument selects which set of workspace MCP tools the server exposes. HeavenBase built-in currently ships full for trusted administrative flows, agent for day-one schema and data work, memory for note-style memory, and memstate for project-scoped memory state. This page uses profile="agent" because it gives the agent enough tools to define entities, inspect schemas, upsert rows, patch rows, count, query, and explain routing while leaving out bulk operations, existence checks, and deletes.

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 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: 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 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": {
    "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 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": {
    "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 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.my-space-mcp "How many entities do I have now in the workspace?"
hb llm session --mcp quickstart.my-space-mcp

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.my-space-mcp --transport http

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="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.my-space-mcp --transport sse and connect to http://127.0.0.1:7001/sse.

4. Agent Profile and Workspace MCP Tools

This tutorial uses profile="agent", HeavenBase’s default day-one workspace MCP surface. It exposes a curated schema-and-data toolkit backed by Catalog and MetaSchema: agents inspect workspace structure through schema tools and discover concrete rows through Catalog-aware listing and description.

Tool	What it offers
`define_entity`	Creates an entity definition from a JSON-compatible schema. Writes the MetaSchema rows that describe fields, logical types, and routing.
`list_entities`	Lists registered entity ids in the workspace—the schema-side directory an agent uses before targeting concrete data.
`describe_entity`	Returns one entity’s fields, logical types, routing plan, and placement metadata from MetaSchema. Use it after `list_entities` when the agent needs the full shape of one entity.
`upsert`	Inserts or replaces one row for one entity. Successful non-system writes update Catalog rows for later discovery.
`get`	Fetches one row by object ID.
`set`	Patches one row and returns the updated row.
`count`	Counts rows for one entity.
`query`	Runs a JSON query with filters, projections, sorting, and limits.
`explain`	Shows the route and handler plan for a query.

The agent profile intentionally leaves out bulk mutation, batch reads, existence checks, and deletes. Use profile="full" only for trusted administrative flows. Keep the model-facing profile narrow and route destructive actions through application code. One workspace can expose multiple MCP toolkits, each with a different profile:

workspace = hb.HeavenBase("support", preset="debug")
agent_tools = workspace.to_mcp(name="support-agent", profile="agent")
admin_tools = workspace.to_mcp(name="support-admin", profile="full")
memory = workspace.to_mcp(name="support-memory", profile="memory")
memstate = workspace.to_mcp(name="support-memstate", profile="memstate")

The agent profile is enough for first-run agents to define schemas, write and patch rows, read context, count rows, query, and inspect route plans. The memory profile is a five-tool note surface (remember, recall, search_memory, list_memory, set_memory). The memstate profile is for versioned project memory (memstate_* verbs). The full profile adds bulk operations, existence checks, and deletes for trusted code paths. HeavenBase also ships a database profile for read/query flows plus run_snippet and suggest_sql when the optional database extension is enabled.

5. Try It Out: A Toy E-Commerce Scenario

Copy each prompt below into your agent chat, in order. Each block is one message you can paste and send.

Set workspace context

Tell the agent which MCP server to use:

Use the `my-space-mcp` MCP for maintaining an e-commerce knowledgebase.

When starting a new session, it is recommended to paste this prompt first to set the minimal workspace context.

Define your business model

Ask the agent to create the core entities, one prompt at a time:

Create a Product entity schema with name, price, category (textual), and availability (default to true).

Create a Customer entity schema with name, email, address (textual), profile (list of texts about the customer).

Create an Order entity schema with order_id, customer_id (reference), product_id (reference), quantity. One order row holds one product; use multiple rows when an order has multiple products.

Daily operations

Seed the workspace with catalog items, customers, and orders:

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

Bob (bob@gmail.com, 456 Oak St) registered but hasn't ordered anything yet.

Bob searched for "chair" and didn't find anything.

Alice (alice@gmail.com, 123 Maple St) ordered 2 keyboards and 1 monitor.

Add a product: "Mesh Office Chair" priced at $199.99 in category "office".

Add a product: "Wooden Chair" priced at $39.99 in category "office".

Add a product: "Wireless Mouse" priced at $49.99 in category "electronics".

Update Bob's address to 789 Pine St.

Wood chair is out of stock.

Analytical questions

Ask analytical questions. Expected answers are shown below each prompt.

What percentage of products in my store cost less than $100?

66.67% (4 out of 6 products)

List all products in the electronics category sorted by price ascending.

Wireless Mouse ($49.99), Ergonomic Keyboard ($89.99), 27-inch 4K Monitor ($349.00)

What's the best-selling product based on total quantity ordered?

Ergonomic Keyboard (2)

How many active customers (at least one order) do I have?

1 (Alice)

What products should I recommend to Alice and Bob based on their profiles and order history? Write a short recommendation pop-up for each of them.

Hi Alice — complete your desk setup
You already run a keyboard-and-monitor setup. Add a Wireless Mouse ($49.99) for a matched input stack, and a Bamboo Desk Organizer ($24.50) to tidy cables and accessories.
Suggested add-ons: Wireless Mouse · Bamboo Desk Organizer

Hi Bob — we found chairs for you
You searched for a chair earlier. The Wooden Chair isn’t available right now, but the Mesh Office Chair ($199.99) is — ergonomic mesh for long sessions.
Suggested for you: Mesh Office Chair

Now you have a persistent, queryable, structured memory surface for your agent. This e-commerce toy example completes without you writing a single CRUD function or defining business logic. The agent inspects the available tools, defines entities on the fly, writes data, and runs queries through the same MCP interface.

Further Exploration

Related resources:

First MCP - generic MCP math toolkit demo
30min Developer Workshop: Tasklist Manager - build Sublinear, an agentic tasklist manager
Workspace - workspace lifecycle and configuration
MCP toolkit reference - workspace MCP tools, profiles, and CLI
Backends - SQLite, PostgreSQL, MySQL, and more

​1. Create an Empty Workspace

​2. Run It

​3. Connect Your Agent

​4. Agent Profile and Workspace MCP Tools

​5. Try It Out: A Toy E-Commerce Scenario

​Further Exploration

1. Create an Empty Workspace

2. Run It

3. Connect Your Agent

4. Agent Profile and Workspace MCP Tools

5. Try It Out: A Toy E-Commerce Scenario

Further Exploration