MCP toolkit reference

Toolkit API

import heavenbase as hb

toolkit = hb.Toolkit("math-tools", namespace="demo", version="1")

Method	Purpose
`Toolkit.add(item, name=...)`	Add a callable, `Capsule`, or `Tool`.
`Toolkit.tool(name=...)`	Decorator that adds a function to the Toolkit.
`Toolkit.run(tool_name, **kwargs)`	Run one tool locally.
`Toolkit.register(registry_config=...)`	Save tool Capsules and the Toolkit manifest. Defaults to `heavenbase.capsule.registry`.
`Toolkit.load(..., registry_config=...)`	Load a Toolkit from registry records by id or namespace/name/version.
`Toolkit.to_fastmcp()`	Build an in-process FastMCP server.
`Toolkit.from_fastmcp(server, name=...)`	Import a FastMCP server as a Toolkit client.
`Toolkit.to_mcp_json(...)`	Return MCP client configuration JSON.
`Toolkit.serve(...)`	Run the FastMCP server.
`Toolkit.to_anthropic_tools(...)`	Export programmatic tool definitions with `allowed_callers`.

Capsule API

Method	Purpose
`Capsule.from_func(func, ...)`	Capture a callable as a Capsule manifest.
`capsule.register(registry_config=...)`	Store the Capsule in the default or configured registry.
`Capsule.load(..., registry_config=...)`	Load by id or namespace/name/version.
`capsule.to_func()`	Restore the callable using source, import path, then trusted binary fallback.
`capsule.run(**kwargs)`	Restore and call the function.
`capsule(args, *kwargs)`	Call the Capsule like the wrapped Python function.
`capsule.to_str(“json"	"yaml"	"source"	"docstring”)`	Convert the Capsule manifest or callable metadata to a text representation.
`Capsule.from_str(text, format="json")`	Restore a Capsule from a JSON or YAML manifest string.

CLI

Command	Purpose
`hb setup`	Initialize global HeavenBase config, the default workspace, and the Capsule/Toolkit registry.
`hb mcp list`	List registered Toolkits.
`hb mcp capsules`	List registered Capsules.
`hb mcp show REF`	Show one Toolkit record.
`hb mcp tools REF`	List tools in a Toolkit.
`hb mcp call REF TOOL --args JSON`	Call one tool from the console.
`hb mcp mcp-json REF`	Print MCP client config JSON.
`hb mcp serve REF`	Serve a Toolkit as MCP.
`hb mcp remove REF`	Tombstone a Toolkit registry row.

Callable serialization

Internal callable serialization lives in heavenbase.capsule.serialize:

from heavenbase.capsule.serialize import CallableSerialization

payload = CallableSerialization.from_func(add, include_cloudpickle=False).to_dict()
capsule = CallableSerialization.from_dict(payload).to_capsule()

Generic JSON serialization uses the same strategy for callables and falls back to a lightweight reference for callables that cannot be captured.

Registry entities

Entity	Contents
`capsule`	Active Capsule manifests.
`capsule-revision`	Append-only Capsule revisions.
`toolkit`	Active Toolkit manifests and Capsule references.
`toolkit-revision`	Append-only Toolkit revisions.

Workspace MCP tools

workspace.to_mcp(...) and workspace.serve(...) expose these native Toolkit tools:

Tool	Purpose
`define_entity`	Create a new entity definition from JSON.
`list_entities`	List registered entity ids.
`describe_entity`	Return one entity definition and route plan.
`upsert`	Insert or replace one row.
`upsert_many`	Insert or replace rows and return ids in input order.
`get`	Fetch one row by id.
`get_many`	Fetch rows by ids in input order.
`set`	Apply one row patch.
`set_many`	Apply row patches and return ids in input order.
`delete`	Delete one target.
`delete_many`	Delete targets in input order.
`exists`	Check one id.
`exists_many`	Check ids in input order.
`count`	Count rows for one entity type.
`query`	Execute a JSON query spec.
`explain`	Explain route and handler choices for a JSON query.

HeavenBase does not expose generic MCP alter_entity or undefine_entity tools yet because entity migration, physical cleanup, Catalog updates, and recovery semantics must be explicit before agents can safely change or drop entity definitions.

Workspace MCP profiles

Use profiles to keep the model-facing tool list small:

Profile	Tools	Use case
`agent`	`define_entity`, `list_entities`, `describe_entity`, `upsert`, `get`, `set`, `count`, `query`, `explain`	First-run agents that need schema discovery, single-row writes, reads, counts, and route explanations.
`memory`	`remember`, `recall`, `search_memory`, `list_memory`, `set_memory`	Note-only memory for agents that should not see generic schema or query tools.
`memstate`	`memstate_remember`, `memstate_set`, `memstate_get`, `memstate_search`, `memstate_history`, `memstate_delete`	Versioned project-keypath memory with browsing, conflict visibility, history, and soft deletes.
`full`	All workspace tools listed above.	Administrative scripts, tests, and trusted agents that need bulk tools, existence checks, and deletes.

The memory profile auto-creates the configured memory entity on first use. Defaults live under heavenbase.mcp.memory: entity defaults to memory-note, default_source to agent, list_limit to 20, and search_limit to 10. For simple memory workflows, use remember for summaries or decisions, recall/list_memory for exact retrieval and browsing, search_memory for fuzzy lookup, and set_memory for exact-key correction. For Memstate-style memory workflows, use profile="memstate". It prefixes keys as project.<project_id>.<keypath>, returns current rows with memstate_get, preserves prior versions for memstate_history, reports conflicting previous values on writes, and creates tombstones with memstate_delete.

Serving options

workspace.serve(
    name="notes",
    transport="http",
    host="127.0.0.1",
    port=7001,
    wait=True,
)

Defaults live under heavenbase.mcp:

Config key	Default
`heavenbase.mcp.transport`	`http`
`heavenbase.mcp.host`	`127.0.0.1`
`heavenbase.mcp.port`	`7001`
`heavenbase.mcp.wait`	`true`

Health check

Use a FastMCP client to verify the server can list and call tools:

from fastmcp import Client

server = toolkit.to_fastmcp()

async with Client(server) as client:
    tools = await client.list_tools()
    result = await client.call_tool("add", {"left": 2, "right": 3})

result.structured_content contains the tool return value under result for scalar Python returns.

Anthropic programmatic tools

Anthropic programmatic tool calling is a separate export path from MCP connector tools:

tool_defs = toolkit.to_anthropic_tools(allowed_callers=["code_execution"])

Each definition includes allowed_callers, name, description, and input_schema. Tool runtime adapters should return strings when called from code execution.

Documentation Index

​Toolkit API

​Capsule API

​CLI

​Callable serialization

​Registry entities

​Workspace MCP tools

​Workspace MCP profiles

​Serving options

​Health check

​Anthropic programmatic tools

​Related pages