MCP Toolkit Reference

MCP is the doorway; the Toolkit decides which rooms have handles.

1. Motivation

A runtime Toolkit can wrap live objects, workspace closures, or a remote FastMCP server. Those values can serve tools now but cannot always be restored later. A persisted Toolkit must reference durable Capsules and belong to one explicit application workspace. HeavenBase therefore keeps construction, persistence, profile assembly, and transport as separate operations. The same Tool contract crosses them, while each boundary stays inspectable.

2. Use the Tool API

API	Purpose
`Tool(callable_or_capsule, name=...)`	Wrap a callable or existing Capsule.
`@Tool` / `@Tool(name=...)`	Bare or configured decorator construction.
`tool(args, *kwargs)`	Call the wrapped function locally.
`tool.run(args, *kwargs)`	Explicit local call.
`tool.set_serializer(...)`	Set a callable or Capsule output serializer.
`tool.run_to_str(args, *kwargs)`	Call and serialize the result.
`tool.to_openai_tool()`	Export an OpenAI-compatible tool definition.

import heavenbase as hb


@hb.Tool(name="add")
def add(left: int, right: int) -> int:
    return left + right

Tool schemas derive from the Capsule signature unless you provide explicit input or output schema metadata. MCP behavior hints live in Tool.annotations, separately from arbitrary Tool.metadata. Use the official wire names: title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

toolkit = hb.Toolkit("catalog", namespace="demo")
toolkit.add(
    lookup_product,
    annotations={
        "title": "Look up product",
        "readOnlyHint": True,
        "idempotentHint": True,
        "openWorldHint": False,
    },
)

Annotations survive Toolkit persistence and FastMCP export/import. They are advisory presentation and risk hints, not authorization; clients must still treat annotations from untrusted servers as untrusted input. Missing hints keep MCP’s conservative defaults.

3. Use the Capsule API

API	Purpose
`Capsule(callable, ...)`	Capture a callable with function-like behavior.
`@Capsule(...)`	Configured decorator capture.
`Capsule.from_func(...)`	Explicit callable capture.
`Capsule.from_code(...)`	Capture trusted source text; executes once during capture.
`Capsule.from_manifest(...)`	Restore from a manifest mapping.
`Capsule.from_str(...)`	Restore a JSON or YAML manifest string.
`capsule.verify()`	Check stored payload fingerprints without execution.
`capsule.to_func()`	Restore the callable.
`capsule.run(...)` / `capsule(...)`	Restore and call.
`capsule.to_str(format)`	Render `json`, `yaml`, `source`, or `docstring`.
`capsule.register(...)`	Store in the advanced Context-private Capsule registry.
`Capsule.load/list/delete(...)`	Administer standalone Capsule rows.

include_cloudpickle defaults to False. Restore and execution are trusted-code operations even when fingerprint verification succeeds.

4. Use the Toolkit API

API	Purpose
`Toolkit(name, tools, namespace=..., version=...)`	Construct an ordered Toolkit.
`toolkit.add(...)` / `add_many(...)`	Add Tool, Capsule, or callable values.
`@toolkit.tool(...)`	Decorator that adds a function.
`toolkit.list_tools()`	Return tool names in declaration order.
`toolkit.run(name, ...)`	Run one Tool and return its Python value.
`toolkit.run_to_str(name, ...)`	Run and serialize one Tool result.
`toolkit.register(ws=..., on_conflict=...)`	Persist Toolkit and referenced Capsules in one workspace.
`Toolkit.load(..., ws=...)`	Load a Toolkit and lazily restore its Capsules.
`Toolkit.list(..., ws=...)`	List Toolkit rows in one workspace.
`Toolkit.describe(..., ws=...)`	Return one raw Toolkit row.
`Toolkit.delete(id, ws=...)`	Tombstone or remove one Toolkit row.
`toolkit.to_fastmcp()`	Build an in-process FastMCP server.
`Toolkit.from_fastmcp(...)`	Build a runtime client Toolkit over a live server.
`toolkit.to_mcp_json(...)`	Return MCP client configuration JSON.
`toolkit.serve(...)`	Serve the Toolkit.
`toolkit.to_anthropic_tools(...)`	Export Anthropic programmatic tool definitions.

ws = hb.HeavenBase("math-app", preset="debug")
toolkit = hb.Toolkit("math", {"add": add}, namespace="demo")
toolkit_id = toolkit.register(ws=ws)

loaded = hb.Toolkit.load(toolkit_id, ws=ws)
assert loaded.run("add", left=2, right=3) == 5

Omitting ws= from Toolkit persistence calls uses existing-only hb.HeavenBase.load(). It never creates a workspace.

5. Understand Workspace-Owned Rows

Entity id	Contents
`sys-capsule`	Capsule identity, manifest, capabilities, fingerprints, status, reason, timestamps
`sys-toolkit`	Toolkit identity, ordered main/serializer Capsule references, serving metadata, status, reason, timestamps

Capsule is the required Extension root. Toolkit is a packaged default root. Toolkit.register(ws=...) ensures the workspace owns both Toolkit and referenced Capsule rows. Standalone Capsule.register() uses an advanced Context-private hidden store for machine/domain administration. Do not confuse that store with application Toolkit persistence.

6. Use Workspace MCP Tools

workspace.to_mcp(profile=...) and workspace.serve(profile=...) assemble Registry-backed Toolkit families. Backend inspection tools project their existing read_only contract to MCP readOnlyHint. The core workspace family includes:

Tool group	Tools
Schema	`define_entity`, `list_entities`, `describe_entity`
Write	`upsert`, `upsert_many`, `set`, `set_many`
Read	`get`, `get_many`, `exists`, `exists_many`, `count`
Delete	`delete`, `delete_many`
Query	`query`, `explain`

There are no generic alter_entity or undefine_entity MCP tools. Entity migration, physical cleanup, Catalog changes, and recovery require explicit domain policy before they are safe for agents.

7. Select a Profile

Profiles are mcp_profile Registry records. They compose exact tool names, Toolkit families, Entity and Skill scopes, one serializer, dependencies, and optional extends.

Profile	Intended surface
`agent`	Curated inspect, read, write, query, explain, and optional Skill tools
`full`	All available workspace tools for trusted administration
`memory`	`remember`, `recall`, `search_memory`, `list_memory`, `set_memory`
`memstate`	Versioned `memstate_*` key-path operations
`database`	Read/query groups plus controlled database helpers

External modules may publish their own Toolkit families and profiles through meta.yaml. The owning Context resolves them before workspace assembly; optional families activate only through declared workspace_requires.

8. Use the MCP CLI

All Toolkit commands accept or resolve an existing workspace:

Command	Purpose
`hb mcp setup --workspace ID`	Enable Toolkit storage in an existing workspace.
`hb mcp list --workspace ID`	List Toolkit rows.
`hb mcp capsules --workspace ID`	List Capsule rows.
`hb mcp show REF --workspace ID`	Show one Toolkit record.
`hb mcp tools REF --workspace ID`	List one Toolkit’s tools.
`hb mcp call REF TOOL --args JSON --workspace ID`	Call one tool.
`hb mcp remove REF --workspace ID`	Remove or tombstone a Toolkit row.
`hb mcp mcp-json REF --workspace ID`	Print client configuration.
`hb mcp stdio REF --workspace ID`	Serve a registered Toolkit over stdio.
`hb mcp serve REF --workspace ID`	Serve a registered Toolkit over the selected transport.

REF accepts Toolkit id, name, or namespace/name:version.

9. Serve and Verify

from fastmcp import Client

server = loaded.to_fastmcp()

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

HeavenBase targets FastMCP 4 and returns native structured tool results when a Tool has an output schema. Serving lifecycle is owned by the FastMCP lifespan rather than a parallel compatibility path. For a workspace profile:

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

Transport defaults live under heavenbase.mcp. Keep unauthenticated HTTP on loopback. Use stdio for local coding-agent integrations when a long-lived network server is unnecessary.

10. Export Anthropic Programmatic Tools

tool_defs = loaded.to_anthropic_tools(
    allowed_callers=["code_execution"],
)

This export path is separate from MCP connector tools. Each definition includes allowed_callers, name, description, and input schema. Execution adapters should return strings when called from code execution.

11. Apply the Trust Checklist

Review Capsule source, layers, schemas, and serializer.
Keep binary fallback disabled unless reviewed local code needs it.
Persist concrete Toolkits in an explicit application workspace.
Use the smallest profile that supports the task.
Namespace external tools and reject collisions.
Treat Tool annotations as hints, never as an authorization decision.
Validate untrusted arguments at the Tool or owning API boundary.
Keep filesystem, credential, network, and destructive authority explicit.
Test real list/call behavior through the intended transport.

Summary

Tool, Capsule, and Toolkit APIs share one callable execution model.
Persisted Toolkits and Capsules belong to an explicit application workspace.
Official MCP annotations and structured results round-trip through FastMCP 4.
Profiles, serializers, and transport configuration keep MCP authority inspectable.

Further Exploration

Related resources:

Capsules - Inspect capture, restore, and trust
Toolkits - Build and persist a tool collection
HeavenBase MCP - Configure workspace serving
First MCP - Complete a small MCP walkthrough
Extensions - Publish external families and profiles

​1. Motivation

​2. Use the Tool API

​3. Use the Capsule API

​4. Use the Toolkit API

​5. Understand Workspace-Owned Rows

​6. Use Workspace MCP Tools

​7. Select a Profile

​8. Use the MCP CLI

​9. Serve and Verify

​10. Export Anthropic Programmatic Tools

​11. Apply the Trust Checklist

​Summary

​Further Exploration

1. Motivation

2. Use the Tool API

3. Use the Capsule API

4. Use the Toolkit API

5. Understand Workspace-Owned Rows

6. Use Workspace MCP Tools

7. Select a Profile

8. Use the MCP CLI

9. Serve and Verify

10. Export Anthropic Programmatic Tools

11. Apply the Trust Checklist

Summary

Further Exploration