> ## Documentation Index > Fetch the complete documentation index at: https://ahvn.top/llms.txt > Use this file to discover all available pages before exploring further. # MCP toolkit reference > Full reference for HeavenBase MCP toolkit tools and schemas. ## Toolkit API ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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.` 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..`, 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 ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ## Related pages * [Capsules](/features/capsules) * [Toolkits](/features/toolkits) * [HeavenBase MCP](/quickstart/heavenbase-mcp) * [First MCP](/quickstart/first-mcp)