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=..., on_conflict=...)`	Save each tool’s main and serializer Capsules, then store the Toolkit manifest. Defaults to `overwrite=True`.
`Toolkit.run_to_str(tool_name, **kwargs)`	Run one tool and return the serialized string through its serializer Capsule.
`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.extensions.system.capsule.serialize:

from heavenbase.extensions.system.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 and metadata entities

Capsules and Toolkits persist as system entities owned by the required system extension:

Entity id	Contents
`sys-capsule`	Active Capsule manifest row with identity, manifest payload, capabilities, fingerprints, and `last_reason` on overwrite.
`sys-toolkit`	Active Toolkit manifest with ordered main and serializer Capsule references per tool.

Workspaces also mirror mcp_profile, mcp_serializer, toolkit_family, storage_profile, sql_dialect, and database_dialect metadata into sys-metaschema rows.

Workspace MCP tools

workspace.to_mcp(...) and workspace.serve(...) assemble registered toolkit families and expose these core workspace 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

MCP exposure uses declarative ProfileSpec objects (config under heavenbase.mcp.profiles.<name> or hb.ext.register_profile). Profiles compose tool groups, toolkit families (WorkspaceToolkitFamilySpec), entity/skill scopes, and a registered serializer.

Profile	Tools	Serializer	Owner
`full`	all workspace tools	`jstr`	system toolkit
`agent`	curated inspect/read/write/query surface plus optional `list_skills` / `read_skill`	`markdown`	system + `agent` extension
`memory`	`remember`, `recall`, `search_memory`, `list_memory`, `set_memory`	`jstr`	`memory` extension
`memstate`	`memstate_*` verbs	`jstr`	`memory` extension
`database`	read/query groups plus `run_snippet`, `suggest_sql`	`jstr`	`database` extension

Profile, serializer, and family specs are mirrored to sys-metaschema and reloaded per workspace; optional extension families auto-enable their extension on first use. 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 execution adapters should return strings when called from code execution.

​Toolkit API

​Capsule API

​CLI

​Callable serialization

​Registry and metadata entities

​Workspace MCP tools

​Workspace MCP profiles

​Serving options

​Health check

​Anthropic programmatic tools

​Related pages