Give the Entity useful reach

Tools let the Entity act on information and its environment. Their registry describes available interfaces; credentials, dependencies, execution policy, and surface connections determine whether a particular call can work.

Discover the running registry

Ask the Entity to use search_tools to find a capability and describe_tool to inspect its exact schema. Telegram /tools also exposes registered tools. Do not depend on one fixed tool count. Configuration and MCP connections change the registry, and a truncated discovery result may return only part of it.

Area	Examples
Research	`search_web`, `fetch_url`
Files and execution	`read_file`, `write_file`, `run_command`, Python and JavaScript execution
Persistent work	Knowledge, journals, projects, reminders, routines
Communication	Configured messaging and voice tools
Spatial	Movement, gestures, panels, objects, environment, and capture
Extensions	Tools discovered from configured MCP subprocesses

The spatial reference documents every shipped spatial tool and its parameters.

Configure capabilities

Harness tool settings live in configs/default.yaml. A top-level tools block in Entity YAML can override them:

tools:
  shell:
    enabled: false
  browser:
    enabled: false
  imagegen:
    enabled: false

Disabling one category does not disable all ways to perform related work. For example, shell and code execution are separate capabilities. Review the complete registry and execution policy for the access you intend to grant.

Choose the execution host

Shell, code, and filesystem tools use the execution client. A configured RPC endpoint takes precedence; local fallback is gated by settings and the deployment environment. For a dedicated local development workspace, an explicit configuration is:

tools:
  shell:
    enabled: true
  execution:
    allow_local: true
    workspace_dir: "./workspace"

Create the directory before use and run ngram from the intended application checkout. This grants local execution; the workspace setting and shell denylist are not a substitute for process isolation. See deployment security.

Add an MCP tool

The v1 MCP hub launches stdio servers. A URL-only HTTP MCP configuration is not handled directly by this hub. Create tools/hello_mcp.py in your application checkout:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello")

@mcp.tool()
def greet(name: str) -> str:
    """Return a greeting for a named person."""
    return f"Hello, {name}."

if __name__ == "__main__":
    mcp.run(transport="stdio")

Add this to the Entity declaration:

mcp_servers:
  hello:
    command: uv
    args: ["run", "python", "tools/hello_mcp.py"]

Start the Entity from the application root. The hub discovers the server tool and registers it as mcp_hello_greet. Ask the Entity to describe that tool, then call it with a name. The example needs no service credential. MCP subprocesses inherit a runtime environment and can have their own access. Keep real credentials in the private environment instead of copying them into committed YAML.

Optional dependencies

Install only the extras needed for your configured capabilities. From the source checkout:

uv sync --extra dev --extra voice --extra pdf

The application also defines browser, imagegen, youtube, and full extras. An installed package does not configure its external backend. Verify the tool result before claiming a capability is operational.

Getting started

Entities

Surfaces

Explore

Give the Entity useful reach

Discover the running registry

Configure capabilities

Choose the execution host

Add an MCP tool

Optional dependencies

​Discover the running registry

​Configure capabilities

​Choose the execution host

​Add an MCP tool

​Optional dependencies

Discover the running registry

Configure capabilities

Choose the execution host

Add an MCP tool

Optional dependencies