@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:
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
All three end up calling the same backend. MCP is just the local adapter that gives an IDE agent typed tools.
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 (currently 0.3.0) pins @hitheo/sdk with ^0.4.0, so a 0.4.x SDK release is picked up automatically; a 0.5.0 SDK 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.