Tools - Theo API Docs

@hitheo/mcp exposes fourteen tools to your IDE agent. Each one wraps a method on @hitheo/sdk and ultimately hits a REST endpoint on https://www.hitheo.ai/api/v1/*. The schemas below are reproduced from packages/mcp/src/tools.ts, so what your IDE sees in its tool catalog is what’s documented here. The tools fall into two groups: execution tools that run work (theo_complete, theo_code, …) and configuration tools that build and shape a key’s orchestrator from natural language (theo_setup_key, theo_set_guardrail, …). Every configuration change is saved immediately and rendered on the dashboard canvas at /dashboard/orchestrator?key=….

Tools never see your API key — @hitheo/mcp loads it once at startup from THEO_API_KEY and signs the underlying HTTP request on the agent’s behalf. The agent only sees the text/JSON the tool returns.

Every configuration tool (theo_setup_key, theo_configure_key, theo_add_skill, theo_assign_skill_to_node, theo_set_guardrail, theo_set_routing) requires the MCP server’s own key to carry the billing scope. Without it those calls return a permission error.

Scope inheritance. Configuration tools inherit the scope of the key the MCP server authenticates with. Point the server at a team key and everything it creates — new keys (theo_setup_key), routing preferences and guardrail policies (theo_set_routing / theo_set_guardrail) — is created under that team, billed to the team, and visible to every member. Point it at a personal key and the same tools stay personal. You never pass a scope explicitly; it follows the key.

Tool catalog

Execution

Tool	Purpose	SDK	REST
`theo_complete`	General-purpose orchestrated completion	`theo.complete()`	`POST /api/v1/completions`
`theo_code`	Code generation with long output budget	`theo.code()`	`POST /api/v1/code`
`theo_research`	Deep research with citations (async)	`theo.research()`	`POST /api/v1/research`
`theo_image`	Image generation	`theo.images()`	`POST /api/v1/images`
`theo_document`	Generate PDF / DOCX / PPTX / XLSX / CSV	`theo.documents()`	`POST /api/v1/documents`
`theo_skill_list`	List installed or marketplace skills	`theo.skills()`	`GET /api/v1/skills`
`theo_skill_install`	Install a skill from the marketplace	`theo.installSkill()`	`POST /api/v1/skills`
`theo_status`	Engine health + latency	`theo.health()`	`GET /api/v1/health`

Configuration (requires `billing` scope)

Tool	Purpose	REST
`theo_setup_key`	Create a new key + a saved, visible orchestrator (preset / per-mode routing / full graph)	`POST /api/v1/keys` + `PUT …/orchestrator-graph`
`theo_configure_key`	Re-plan an existing key (same options as setup)	`PUT …/orchestrator-graph`
`theo_add_skill`	Install + attach a skill to a key (optionally scoped to one mode)	`PUT …/keys/{id}/skills`
`theo_assign_skill_to_node`	Attach a skill to graph node(s), matched by id / label / mode / engine	`PUT …/orchestrator-graph`
`theo_set_guardrail`	Add a guardrail as an input/output node (or key-level)	`PUT …/keys/{id}/guardrails`
`theo_set_routing`	Append routing rules + insert a Router node	`PUT …/keys/{id}/routing-preference`

`theo_complete`

Run an AI completion through Theo’s orchestration engine. Theo automatically classifies intent, selects the best engine across 300+ AI models, injects domain skills, executes tools, and returns the response. Use this for any general AI task: writing, analysis, planning, Q&A.

Input schema

Field	Type	Required	Description
`prompt`	`string`	✅	The prompt or question to send to Theo.
`mode`	`"auto" \| "fast" \| "think" \| "code" \| "research" \| "roast"`	—	Execution mode. `auto` lets Theo classify. `fast` uses a lightweight model. `think` uses deep reasoning. `code` optimizes for code. Default: `auto`.
`skills`	`string[]`	—	Skill slugs to activate (e.g. `["deep-research", "content-writer"]`).
`conversation_id`	`string`	—	Continue an existing conversation by ID.

When theo.config.json defines persona, skills, defaultMode, or tools, those values are merged into the request — see Project Config.

Example agent invocation

Use theo_complete to draft a release-note summary for the diff in HEAD~3..HEAD.

Example response (truncated)

Here's a release-note summary for the last three commits:
- ...

---
Tools used: web_search (ok), summarize_diff (ok)
Model: Theo Reason | Mode: think | Cost: 3¢

Notes

Output includes a one-line tail with the resolved model, mode, and cost so the agent sees how the request was routed.
Costs are reconciled after execution and reflect what your account was billed.

`theo_code`

Generate code using Theo. Routes to the Theo Code engine for best-in-class code generation with an extended output budget. Returns generated code and any artifacts (full files, project scaffolds). Use this when the task is primarily about writing, generating, or scaffolding code.

Input schema

Field	Type	Required	Description
`prompt`	`string`	✅	Describe the code you want generated.
`language`	`string`	—	Target programming language (e.g. `typescript`, `python`, `go`).
`framework`	`string`	—	Target framework (e.g. `nextjs`, `express`, `fastapi`, `react`).

Example agent invocation

Use theo_code to scaffold a FastAPI service with a /health route and a /chat
SSE route. language=python, framework=fastapi.

The tool returns the generated content plus an Artifacts: block with JSON describing any files created.

`theo_research`

Run deep research on a topic. Theo plans 3–6 focused search queries, runs them in parallel, deduplicates sources, and synthesizes a structured report with citations. This is an async operation — the MCP server polls until the underlying job completes (default budget: 120 seconds at a 3-second interval) and returns the final report.

Input schema

Field	Type	Required	Description
`prompt`	`string`	✅	The research question or topic.
`depth`	`"basic" \| "advanced"`	—	`basic` is faster; `advanced` is more thorough. Default: `basic`.

Example agent invocation

Use theo_research with depth="advanced" to compare PostgreSQL native partitioning
vs Citus for a write-heavy time-series workload.

Failure handling

If the research job fails or times out, the tool returns a single text payload starting with Research failed: so the agent can decide whether to retry with a narrower prompt.

`theo_image`

Generate images using Theo. Routes to the Theo Create engine with automatic provider fallback. Returns image URLs. Use for logos, illustrations, mockups, concept art, or any visual content.

Input schema

Field	Type	Required	Description
`prompt`	`string`	✅	Describe the image to generate.
`style`	`string`	—	Visual style (e.g. `photorealistic`, `illustration`, `3d`, `pixel`).
`aspect_ratio`	`"1:1" \| "16:9" \| "9:16" \| "4:3" \| "3:4"`	—	Aspect ratio. Default: `1:1`.

Example response

Image 1: https://artifacts.hitheo.ai/img/<id>.png [theo-vision]

Cost: 5¢

Each line corresponds to one image; if the request asked for multiple, you get one URL per image plus a final cost line.

`theo_document`

Generate a formatted document. Theo creates the document and returns a download URL on artifacts.hitheo.ai. Use for reports, presentations, spreadsheets, and data exports.

Input schema

Field	Type	Required	Description
`prompt`	`string`	✅	Describe the document to generate.
`format`	`"pdf" \| "docx" \| "pptx" \| "xlsx" \| "csv"`	—	Output format. Default: `pdf`.

Example agent invocation

Use theo_document with format="pptx" to build a 7-slide pitch deck for an
AI-native EHR called SentryOS.

Example response

Document: SentryOS Pitch Deck
Format: pptx
Download: https://artifacts.hitheo.ai/doc/<id>.pptx

Cost: 3¢

`theo_skill_list`

List available Theo skills. Skills are packages of domain knowledge and tools that extend Theo’s capabilities (like apps for AI). Filter to either installed (active on this account) or marketplace (available to install).

Input schema

Field	Type	Required	Description
`filter`	`"installed" \| "marketplace"`	—	Filter to installed skills or marketplace catalog. Default: all visible.

The tool returns a pretty-printed JSON array of skill records (id, slug, name, description, version, …). Agents typically pair this with theo_skill_install.

`theo_skill_install`

Install a skill from the Theo marketplace. Once installed, the skill’s domain knowledge and tools are available on every completion (and inside every subsequent theo_complete MCP call).

Input schema

Field	Type	Required	Description
`skill_id`	`string`	✅	The skill ID to install.

Example response

Skill skill_a1b2c3 installed successfully.

`theo_status`

Check Theo’s health and engine availability. Returns engine status, latency, and infrastructure health. Use to verify the connection works or diagnose issues from inside the IDE.

Input schema

No parameters.

Example response

Status: healthy
Version: 2026-03-28
Engines:
  theo-core: healthy
  theo-vision: healthy
  theo-search: healthy

If the tool returns anything other than Status: healthy, run theo verify on the host to dig in.

`theo_setup_key`

Create a new Theo API key and build a saved, visible orchestrator in one call — no hand-drawing on the canvas. Specify the plan one of three ways (precedence: graph > routing > use_case):

use_case — a single-engine preset. coding pins a code engine as a deterministic passthrough (a clean drop-in backend for Warp / Cursor); chat a fast engine; raw an engine you choose.
routing — per-mode engine bindings. Theo’s classifier splits each request into a mode and you pin an engine per mode.
graph — a full custom orchestrator graph { enabled, nodes, edges }, applied as-is.

Returns the raw key (shown once) plus a dashboard link. The orchestrator is enabled immediately.

Input schema

Field	Type	Notes
`use_case`	`"coding" \| "chat" \| "raw"`	Single-engine preset. `coding` is the default.
`model`	`string`	Engine id to pin for the preset (e.g. `anthropic/claude-opus-4.8`). Required for `raw`.
`routing`	`Array<{ mode, model }>`	Per-mode engine bindings, e.g. `[{ "mode": "fast", "model": "arca-velox-5.1" }, { "mode": "think", "model": "arca-magnus-5.1" }]`.
`graph`	`{ enabled, nodes[], edges[] }`	Advanced: a full graph. Overrides `use_case` / `routing`.
`name`	`string`	Optional name for the new key.

Example agent invocation

Use theo_setup_key to make a key where light requests go to Arca Velox and heavy
ones to Arca Magnus.

theo_setup_key { "routing": [
  { "mode": "fast",  "model": "arca-velox-5.1" },
  { "mode": "think", "model": "arca-magnus-5.1" }
] }

Example response (truncated)

✅ Created key "orchestrator (via MCP)".

API key (shown once — store it now):
  theo_sk_…

Built & saved an orchestrator graph (classifier → one engine per mode):
  fast → arca-velox-5.1
  think → arca-magnus-5.1

Review or extend this setup in the dashboard:
  https://www.hitheo.ai/dashboard/orchestrator?key=…

`theo_configure_key`

Re-plan an existing key — the same three options as theo_setup_key (use_case / routing / graph, same precedence). Changes reflect on the dashboard canvas immediately. Returns a dashboard link.

Input schema

Field	Type	Notes
`key_id`	`string`	Required. The API key UUID to configure.
`use_case`	`"coding" \| "chat" \| "raw"`	Single-engine preset.
`model`	`string`	Engine id override; required for `raw`.
`routing`	`Array<{ mode, model }>`	Per-mode engine bindings.
`graph`	`{ enabled, nodes[], edges[] }`	Full graph; overrides the others.

Example agent invocation

Use theo_configure_key on key <uuid> to send everything to Claude Opus.

theo_configure_key { "key_id": "<uuid>", "use_case": "raw", "model": "anthropic/claude-opus-4.8" }

`theo_add_skill`

Install a skill (from the marketplace, if needed) and attach it to a key’s allowlist so that key can call it. Optionally scope it to a single mode. Idempotent — re-adding the same (skill, mode) is a no-op.

Input schema

Field	Type	Notes
`key_id`	`string`	Required. The API key UUID.
`skill`	`string`	Required. Skill slug, name, or id (e.g. `deep-research`).
`mode`	`string`	Optional: scope to one mode (`fast` / `think` / `code` / `research` / `roast` / `genui` / `data_extraction` / `vision`). Omit = all modes.

Example agent invocation

Add the deep-research skill to key <uuid>, but only for the think mode.

theo_add_skill { "key_id": "<uuid>", "skill": "deep-research", "mode": "think" }

If the skill can’t be resolved, the tool returns No skill matches "…" so the agent can call theo_skill_list and retry.

`theo_assign_skill_to_node`

Attach a skill to one or more model nodes in a key’s orchestrator graph, so the skill applies only there. The target is matched by node id, label, the mode it handles, or the engine it runs — and the skill is attached to every match. So a query naming an engine or mode shared by two or more nodes hits all of them (e.g. sonnet attaches to every node running anthropic/claude-sonnet-4.6). Requires the key to already have a graph. If nothing matches, the tool returns the list of available nodes.

Input schema

Field	Type	Notes
`key_id`	`string`	Required. The API key UUID.
`node`	`string`	Required. Node id, label, the mode it handles (`code`), or the engine it runs (`sonnet`, `arca-magnus-5.1`). Matches every node with that mode/engine.
`skill`	`string`	Required. Skill slug, name, or id.

Example agent invocation

Put the deep-research skill on every node running sonnet on key <uuid>.

theo_assign_skill_to_node { "key_id": "<uuid>", "node": "sonnet", "skill": "deep-research" }

✅ Skill "deep research" (deep-research) attached to 2 nodes (think, code) on key <uuid>.

`theo_set_guardrail`

Bind a Gateway Guardrails policy to a key. Pass an existing policy name/id, or a preset name (e.g. PII-safe, Injection guard) to create a policy from that template and bind it. On a key with an orchestrator graph the policy is added as a Guardrail node on the canvas:

an input node (after Entry, or after the classifier when scoped) screens the prompt;
an output node (after the model) screens the reply.

The phase is inferred from the policy’s own rule phases (input / output / both) unless you pass phase explicitly. Pass mode (a mode or engine name) to scope the guardrail to just that branch — it attaches to every node with that mode/engine. On a key without a graph, the policy is bound key-level (screens both phases per its rules). remove: true clears guardrails; add phase to remove only the input or output checkpoint.

Input schema

Field	Type	Notes
`key_id`	`string`	Required. The API key UUID.
`policy`	`string`	An existing policy name/id, or a preset name.
`phase`	`"input" \| "output" \| "both"`	Where it runs. Omit to infer from the policy. Also filters `remove`.
`mode`	`string`	Optional: scope to one branch — a mode (`think`) or engine (`sonnet`, `anthropic/claude-opus-4.8`). Hits every matching node.
`remove`	`boolean`	Unbind guardrails. Combine with `phase` to remove only input or output.

Example agent invocations

Add PII-safe on the output of key <uuid>.

theo_set_guardrail { "key_id": "<uuid>", "policy": "PII-safe", "phase": "output" }

Add an injection guard on the input of just the think branch of key <uuid>.

theo_set_guardrail { "key_id": "<uuid>", "policy": "Injection guard", "phase": "input", "mode": "think" }

Remove only the output guardrail from key <uuid>.

theo_set_guardrail { "key_id": "<uuid>", "remove": true, "phase": "output" }

`theo_set_routing`

Bind a Routing Studio preference to a key — either an existing preference by name/id, or create rules inline (pattern keyword/regex → mode). Rules are additive by default: new rules are appended to the key’s current routing (deduped), so asking for a second rule keeps the first. Pass replace: true to reset instead. On a graph key a single Router node is inserted (Entry → … → Router → Classifier) so the rules actually apply in-path and show on the canvas; a rule whose target mode has no engine node triggers a warning. remove: true clears routing.

Input schema

Field	Type	Notes
`key_id`	`string`	Required. The API key UUID.
`preference`	`string`	An existing routing-preference name or id to bind.
`rules`	`Array<{ pattern, mode, engine? }>`	Rules to add: keyword/regex → mode (optional pinned engine).
`name`	`string`	Optional name for a preference created from `rules`.
`replace`	`boolean`	Replace the key’s rules instead of appending (default: append).
`remove`	`boolean`	Unbind the routing preference from the key.

Example agent invocation

On key <uuid>, route anything mentioning "invoice" to code.

theo_set_routing { "key_id": "<uuid>", "rules": [ { "pattern": "invoice", "mode": "code" } ] }

A second call adds to the first:

✅ Added 1 routing rule to key <uuid> (2 total):
  /contract/i → think

Reference

Engines (config surface — real engine names are intentional here): arca-velox-5.1 (fast), arca-magnus-5.1 (deep reasoning), anthropic/claude-sonnet-4.6, anthropic/claude-opus-4.8, anthropic/claude-haiku-4.5, google/gemini-2.5-pro, openai/gpt-4.1, plus your own custom:<providerId>:<model>. Modes: fast, think, code, research, roast, genui, data_extraction, vision, image, video. Guardrail presets: e.g. PII-safe, Injection guard. On a mismatch the tool lists the available policies and presets.

Errors

When any tool throws (network error, API error envelope, polling timeout), the MCP server formats it as:

Theo error: <message>

The agent sees the text as a normal tool result, not a JSON-RPC error, so it can read and react instead of bailing. The full structured error is also visible in your MCP server logs if your IDE surfaces them. See Troubleshooting for the most common failure modes.

​Tool catalog

​Execution

​Configuration (requires billing scope)

​theo_complete

​Input schema

​Example agent invocation

​Example response (truncated)

​Notes

​theo_code

​Input schema

​Example agent invocation

​theo_research

​Input schema

​Example agent invocation

​Failure handling

​theo_image

​Input schema

​Example response

​theo_document

​Input schema

​Example agent invocation

​Example response

​theo_skill_list

​Input schema

​theo_skill_install

​Input schema

​Example response

​theo_status

​Input schema

​Example response

​theo_setup_key

​Input schema

​Example agent invocation

​Example response (truncated)

​theo_configure_key

​Input schema

​Example agent invocation

​theo_add_skill

​Input schema

​Example agent invocation

​theo_assign_skill_to_node

​Input schema

​Example agent invocation

​theo_set_guardrail

​Input schema

​Example agent invocations

​theo_set_routing

​Input schema

​Example agent invocation

​Reference

​Errors

Tool catalog

Execution

Configuration (requires `billing` scope)

`theo_complete`

Input schema

Example agent invocation

Example response (truncated)

Notes

`theo_code`

Input schema

Example agent invocation

`theo_research`

Input schema

Example agent invocation

Failure handling

`theo_image`

Input schema

Example response

`theo_document`

Input schema

Example agent invocation

Example response

`theo_skill_list`

Input schema

`theo_skill_install`

Input schema

Example response

`theo_status`

Input schema

Example response

`theo_setup_key`

Input schema

Example agent invocation

Example response (truncated)

`theo_configure_key`

Input schema

Example agent invocation

`theo_add_skill`

Input schema

Example agent invocation

`theo_assign_skill_to_node`

Input schema

Example agent invocation

`theo_set_guardrail`

Input schema

Example agent invocations

`theo_set_routing`

Input schema

Example agent invocation

Reference

Errors