Documentation Index
Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
Use this file to discover all available pages before exploring further.
@hitheo/mcp exposes eight tools to your IDE agent. Each one wraps a method on @hitheo/sdk and ultimately hits a single REST endpoint on https://www.hitheo.ai/api/v1/*. The schemas below are reproduced verbatim from packages/mcp/src/tools.ts, so what your IDE sees in its tool catalog is what’s documented here.
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.
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.
| 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. |
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.
| 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.
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.
| 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.
| 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¢
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.
| 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).
| Field | Type | Required | Description |
|---|
filter | "installed" | "marketplace" | — | Filter to installed skills or marketplace catalog. Default: all visible. |
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).
| 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.
No parameters.
Example response
Status: healthy
Version: 2026-03-28
Engines:
theo-core: healthy
theo-vision: healthy
theo-search: healthy
Status: healthy, run theo verify on the host to dig in.
Errors
When any tool throws (network error, API error envelope, polling timeout), the MCP server formats it as:
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.