> ## 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.

# MCP Server Overview

> How Theo plugs into Cursor, Claude Code, Warp, Windsurf, VS Code, and any other MCP-compatible IDE via @hitheo/mcp.

Theo exposes its full orchestration engine as a local **Model Context Protocol (MCP)** server, published as the [`@hitheo/mcp`](https://www.npmjs.com/package/@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](https://modelcontextprotocol.io) 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`](/mcp/tools#theo_complete), [`theo_code`](/mcp/tools#theo_code), [`theo_research`](/mcp/tools#theo_research), [`theo_image`](/mcp/tools#theo_image), [`theo_document`](/mcp/tools#theo_document), [`theo_skill_list`](/mcp/tools#theo_skill_list), [`theo_skill_install`](/mcp/tools#theo_skill_install), [`theo_status`](/mcp/tools#theo_status).
* **3 resources**: [`theo://models`](/mcp/resources#theo-models), [`theo://skills/installed`](/mcp/resources#theo-skills-installed), [`theo://health`](/mcp/resources#theo-health).
* **Project config**: an optional [`theo.config.json`](/mcp/project-config) in the repo root that injects `persona`, `skills`, `tools`, `defaultMode`, `temperature`, and `metadata` into every tool call.

## Request flow

```mermaid theme={null}
sequenceDiagram
    participant IDE as IDE Agent
    participant MCP as @hitheo/mcp (stdio)
    participant SDK as @hitheo/sdk
    participant API as api.hitheo.ai
    IDE->>MCP: tools/call theo_complete { prompt }
    MCP->>MCP: load theo.config.json (cwd)
    MCP->>SDK: client.complete({ prompt, persona, skills, ... })
    SDK->>API: POST /api/v1/completions
    API-->>SDK: { content, model, usage, ... }
    SDK-->>MCP: typed response
    MCP-->>IDE: text content (Theo's reply)
```

A few invariants worth knowing:

1. **The IDE launches the server**, not you. IDEs spawn `npx -y @hitheo/mcp` on demand and tear it down when the workspace closes.
2. **Transport is stdio**. There is no inbound network port; the server only makes outbound HTTPS calls to `https://www.hitheo.ai`.
3. **Auth is your normal API key**. `THEO_API_KEY` is read once at startup and reused for every request. The key never leaves the server process; the IDE never sees it.
4. **`theo.config.json` is loaded from the current working directory** (the IDE workspace root) at startup. JS/TS variants are ignored by default — see [Security](/mcp/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`](/sdk-reference/installation)) |
| Any other language, CI, curl, webhooks | **REST** ([`/api/v1/*`](/api-reference/overview))      |

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:

```bash theme={null}
export THEO_API_KEY=theo_sk_...
npx -y @hitheo/mcp
```

The process reads `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](/cli-reference/overview):

```bash theme={null}
theo verify   # machine-readable JSON, exits non-zero on failure
theo status   # human-readable; probes both apex and www
```

If both pass, MCP will work inside any IDE configured with the same key.

## Versioning

`@hitheo/mcp` follows the [pre-1.0 semver policy](/changelog) 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](/security/authentication#supply-chain-verifying-npm-packages) starting at `0.1.4`. Verify before installing:

```bash theme={null}
npm audit signatures @hitheo/mcp
```

## Next steps

* **[Install](/mcp/install)** — set up MCP in your IDE (auto-detect or per-IDE).
* **[Tools](/mcp/tools)** — what each tool does, schemas, examples.
* **[Resources](/mcp/resources)** — the three `theo://` URIs your agent can read.
* **[Project Config](/mcp/project-config)** — pin a persona, default skills, or inline tools per repo.
* **[Troubleshooting](/mcp/troubleshooting)** — common setup failures and fixes.
* **[Security](/mcp/security)** — threat model and sandbox semantics.