> ## Documentation Index > Fetch the complete documentation index at: https://ahvn.top/llms.txt > Use this file to discover all available pages before exploring further. # HeavenBase MCP > Expose an empty HeavenBase workspace over MCP and let your agent do the rest: no schema, no code, just data. *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: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python serve_space.py ``` The server prints the client config and starts listening: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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`): ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}} [mcp_servers.my-space-mcp] url = "http://127.0.0.1:7001/mcp" ``` CLI: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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`: ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}} [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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "$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`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "mcp": { "servers": { "my-space-mcp": { "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.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`: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```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`. 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.my-space-mcp --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="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](/features/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: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. Tell the agent which MCP server to use: ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. Ask the agent to create the core entities, one prompt at a time: ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Create a Product entity schema with name, price, category (textual), and availability (default to true). ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Create a Customer entity schema with name, email, address (textual), profile (list of texts about the customer). ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ``` Seed the workspace with catalog items, customers, and orders: ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Add a product: "Ergonomic Keyboard" priced at $89.99 in category "electronics". ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Add a product: "27-inch 4K Monitor" priced at $349.00 in category "electronics". ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Add a product: "Bamboo Desk Organizer" priced at $24.50 in category "office". ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Bob (bob@gmail.com, 456 Oak St) registered but hasn't ordered anything yet. ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Bob searched for "chair" and didn't find anything. ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Alice (alice@gmail.com, 123 Maple St) ordered 2 keyboards and 1 monitor. ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Add a product: "Mesh Office Chair" priced at $199.99 in category "office". ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Add a product: "Wooden Chair" priced at $39.99 in category "office". ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Add a product: "Wireless Mouse" priced at $49.99 in category "electronics". ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Update Bob's address to 789 Pine St. ``` ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} Wood chair is out of stock. ``` Ask analytical questions. Expected answers are shown below each prompt. ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} What percentage of products in my store cost less than $100? ``` 66.67% (4 out of 6 products) ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} 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) ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} What's the best-selling product based on total quantity ordered? ``` Ergonomic Keyboard (2) ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} How many active customers (at least one order) do I have? ``` 1 (Alice) ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/quickstart/first-mcp) - generic MCP math toolkit demo * [30min Developer Workshop: Tasklist Manager](/quickstart/sublinear-workshop) - build Sublinear, an agentic tasklist manager * [Workspace](/features/workspace) - workspace lifecycle and configuration * [MCP toolkit reference](/reference/mcp-toolkit) - workspace MCP tools, profiles, and CLI * [Backends](/features/backends) - SQLite, PostgreSQL, MySQL, and more