Theo exposes its full orchestration engine as a local Model Context Protocol (MCP) server, published as theDocumentation 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 npm package. Any MCP-compatible IDE — Cursor, Claude Code, Warp, Windsurf, VS Code, and others — can launch it on demand and call Theo as a set of tools and resources.
What is MCP
The Model Context Protocol is an open standard for letting an LLM-powered agent invoke tools and read resources hosted by a separate process. The host (your IDE’s agent) speaks JSON-RPC over stdio to a server (@hitheo/mcp) and receives back a typed catalog of tools, resources, and prompts.
Concretely, MCP gives your IDE three primitives:
| Primitive | What it is | Theo example |
|---|---|---|
| Tool | A callable function with a JSON-Schema input | theo_complete, theo_image |
| Resource | A read-only URL the agent can fetch for context | theo://models, theo://health |
| Prompt | A reusable prompt template | (not exposed by @hitheo/mcp today) |
What @hitheo/mcp does
@hitheo/mcp is a stdio MCP server that wraps the official @hitheo/sdk and forwards calls to the Theo REST API (https://www.hitheo.ai/api/v1/*). It is not a separate Theo backend — it is a thin local adapter that converts MCP tool calls into authenticated API calls using your THEO_API_KEY.
This means every tool you invoke from an IDE agent runs through the exact same orchestration pipeline (intent classification → model routing → skills → tool execution) as a direct API call. Skills you have installed, custom personas, project tools — all of it applies inside the IDE.
Surface area
The server currently exposes:- 8 tools:
theo_complete,theo_code,theo_research,theo_image,theo_document,theo_skill_list,theo_skill_install,theo_status. - 3 resources:
theo://models,theo://skills/installed,theo://health. - Project config: an optional
theo.config.jsonin the repo root that injectspersona,skills,tools,defaultMode,temperature, andmetadatainto every tool call.
Request flow
A few invariants worth knowing:- The IDE launches the server, not you. IDEs spawn
npx -y @hitheo/mcpon demand and tear it down when the workspace closes. - Transport is stdio. There is no inbound network port; the server only makes outbound HTTPS calls to
https://www.hitheo.ai. - Auth is your normal API key.
THEO_API_KEYis read once at startup and reused for every request. The key never leaves the server process; the IDE never sees it. theo.config.jsonis loaded from the current working directory (the IDE workspace root) at startup. JS/TS variants are ignored by default — see Security.
How it compares to the SDK and REST API
| Use case | Best surface |
|---|---|
| Inside an IDE agent, no code to write | MCP (@hitheo/mcp) |
| Your own TypeScript/Node app or worker | SDK (@hitheo/sdk) |
| Any other language, CI, curl, webhooks | REST (/api/v1/*) |
Smoke test: confirm it works
You can launch the server by hand to verify the install pipeline and your API key:THEO_API_KEY from the environment, opens a stdio MCP transport, and waits silently for JSON-RPC messages. Press Ctrl+C to exit — silence is the expected behavior, because IDEs (not humans) talk to it.
For a richer end-to-end check that also exercises the network path, use the CLI:
Versioning
@hitheo/mcp follows the pre-1.0 semver policy used by the rest of the Theo packages: minor bumps are the breaking-change signal (not major), matching how npm’s ^ operator resolves 0.x.y. The MCP server pins @hitheo/sdk with ^0.2.2, so a 0.2.x SDK release is picked up automatically; a 0.3.0 release requires bumping the MCP server.
Every published tarball ships with signed npm provenance starting at 0.1.4. Verify before installing:
Next steps
- Install — set up MCP in your IDE (auto-detect or per-IDE).
- Tools — what each tool does, schemas, examples.
- Resources — the three
theo://URIs your agent can read. - Project Config — pin a persona, default skills, or inline tools per repo.
- Troubleshooting — common setup failures and fixes.
- Security — threat model and sandbox semantics.