HeavenBase MCP

An empty workspace is a blank canvas with a query planner hiding behind it.

This tutorial exposes one HeavenBase workspace as a live MCP server. The agent can define entities, write rows, inspect schemas, and query data without you writing a transport layer or CRUD wrapper. This surface differs from a registered Toolkit. workspace.serve(...) closes over one live workspace object and remains available only while that process runs. Registered Toolkits persist their callable Capsules as workspace rows and can be loaded later by reference.

1. Motivation

Giving an agent a database password exposes storage without explaining the domain. Writing a custom MCP server explains the domain, but often duplicates schema validation, routing, query parsing, and serialization. HeavenBase exposes the workspace it already owns:

workspace = hb.HeavenBase("my-space", preset="debug")
workspace.serve(profile="agent", wait=True)

The profile limits the model-facing surface while every tool still uses the same entities, Catalog, MetaSchema, routing plan, and backend authority as Python code.

2. Create and Serve an Empty Workspace

Create serve_space.py:

import heavenbase as hb


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

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

workspace.serve(
    name="my-space-mcp",
    profile="agent",
    transport="http",
    host="127.0.0.1",
    port=7001,
    wait=True,
)

Run it:

python serve_space.py

The debug preset gives the tutorial a local SQLite-backed workspace without requiring Docker. Re-running the script reopens the registered workspace and keeps its data.

Do not put workspace.drop() in the server script unless every start should destroy the workspace. Stop the server first, then drop the workspace explicitly when you truly want to remove its owned data.

The server listens at http://127.0.0.1:7001/mcp. Keep this process running while external clients use the tools.

3. Understand the Live Boundary

workspace.to_mcp(...), workspace.to_mcp_json(...), and workspace.serve(...) create a runtime-only Toolkit that closes over the current workspace object. That Toolkit cannot be registered as a durable Capsule Toolkit because its functions depend on live workspace and backend objects. Persisted state still survives in the workspace; the MCP transport itself does not.

Surface	Owner	Survives server exit	How it is reopened
Workspace data and schemas	`my-space` workspace	Yes	`hb.HeavenBase.load("my-space")`
Live workspace MCP Toolkit	`serve_space.py` process	No	Run `workspace.serve(...)` again
Registered Capsule Toolkit	Explicit workspace rows	Yes	`hb.Toolkit.load(..., ws=workspace)`

Use First MCP when you need durable callable tools. Use this page when you want agents to operate on one live application workspace.

4. Choose an Explicit Profile

The profile is an allowlisted MCP surface, not a request to enable every extension.

Profile	Intended surface	Requirement
`agent`	Define and inspect entities; upsert, get, patch, count, query, and explain	Built-in `toolkit` extension
`full`	Trusted administrative surface including bulk operations and deletes	Built-in `toolkit` extension
`memory`	Five note-memory tools	Enable `memory`
`memstate`	Versioned project keypath memory	Enable `memory`
`database`	Browse ingested schemas and run read-only SQL snippets	Enable `database`

The tutorial uses agent. It omits bulk mutation, existence checks, and deletes while retaining the tools needed for first-day schema and data work. Enable optional roots before selecting their profiles:

memory_workspace = hb.HeavenBase("memory-space", preset="debug")
memory_workspace.enable_extension("memory")
memory_tools = memory_workspace.to_mcp(profile="memory")

database_workspace = hb.HeavenBase("database-space", preset="debug")
database_workspace.enable_extension("database")
database_tools = database_workspace.to_mcp(profile="database")

Enabling memory does not silently enable database, and choosing profile="database" does not install the database extension for you. The workspace manifest records the roots you explicitly selected.

5. Connect a Client

Configure the running Streamable HTTP endpoint in one client.

Claude Code
Codex
VS Code

Add and verify the server:

claude mcp add --transport http my-space-mcp http://127.0.0.1:7001/mcp
claude mcp list

Start a new session and run /mcp before asking the agent to use the workspace.

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

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

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

The JSON printed by workspace.to_mcp_json(...) is a portable starting point for clients that use the common mcpServers shape.

6. Try a Small Store

Send these prompts in order.

Define the model

Use `my-space-mcp`. Define Product with name, price, category, and available;
define Customer with name and email; define Order with customer_id, product_id,
and quantity. Show me the resulting entity summaries.

Add data

Add two products: an Ergonomic Keyboard for 89.99 and a 4K Monitor for 349.00,
both in electronics and available. Add Alice, then record an order in which
Alice buys two keyboards.

Ask a question

Query the workspace and tell me which product is the best seller by quantity.
Explain which entities and rows support the answer.

The agent defines schema through MetaSchema, writes concrete rows, discovers them through Catalog-aware tools, and queries them through the same routing system used by Python callers.

Summary

Workspace MCP closes over one live workspace and must be served by a running process.
Workspace data persists independently from that transport process.
Profiles expose deliberate tool sets; optional profiles require their extensions first.
Registered Capsule Toolkits are a different persistence mechanism with explicit workspace ownership.

Further Exploration

Related resources:

First MCP - Persist callable tools in a workspace
Workspace - Understand workspace ownership and lifecycle
MCP Toolkit Reference - Review profiles and tool contracts
Memory Agent Workshop - Enable and use memory explicitly
Data Analysis Workshop - Enable database analysis explicitly
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 and Serve an Empty Workspace

3. Understand the Live Boundary

4. Choose an Explicit Profile

5. Connect a Client

6. Try a Small Store

Summary

Further Exploration

​1. Motivation

​2. Create and Serve an Empty Workspace

​3. Understand the Live Boundary

​4. Choose an Explicit Profile

​5. Connect a Client

​6. Try a Small Store

​Summary

​Further Exploration

1. Motivation

2. Create and Serve an Empty Workspace

3. Understand the Live Boundary

4. Choose an Explicit Profile

5. Connect a Client

6. Try a Small Store

Summary

Further Exploration