Skip to main content

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.

In MCP, resources are read-only URIs an agent can pull for context without invoking a tool. @hitheo/mcp exposes three:
URIMime typeDescription
theo://modelsapplication/jsonAvailable Theo models and their routing config
theo://skills/installedapplication/jsonSkills active on the current API key
theo://healthapplication/jsonLive provider/engine health and version
All three are derived live from the API — no caching, no transformation. The MCP server simply forwards them with application/json. If the underlying call fails, the resource returns a text/plain body of the form Error reading <uri>: <message> so the agent can still surface something useful.
Resources are a read-only context channel. They are not state-changing — the agent can pull them whenever it needs grounding without spending a tool turn or burning extra credits. (Reading a resource still hits the underlying API, but no AI inference happens.)

​
theo://models

Returns the array your account can route to, with the same shape as GET /api/v1/models. When to use it: before asking Theo to use a specific model, or when the agent wants to explain to the user what engine handled a request. 
[
  {
    "mode": "auto",
    "model_id": "theo-1-flash",
    "label": "Theo Flash",
    "engine": "theo-core",
    "description": "Fast general-purpose model"
  },
  {
    "mode": "code",
    "model_id": "theo-1-code",
    "label": "Theo Code",
    "engine": "theo-core",
    "description": "Long-form code generation"
  }
]
Backed by theo.models() → GET /api/v1/models.

​
theo://skills/installed

Returns the list of skills currently installed for the API key the MCP server is using. Same shape as theo_skill_list with filter="installed". When to use it: before the agent suggests installing a skill (so it doesn’t recommend something the user already has), or before invoking theo_complete with a skills array (to validate slugs). 
[
  {
    "id": "skill_a1b2c3",
    "slug": "deep-research",
    "name": "Deep Research",
    "description": "Multi-step research with citations",
    "version": "1.4.0"
  }
]
Backed by theo.skills("installed") → GET /api/v1/skills?filter=installed.

​
theo://health

Live system health — engine availability, latency, infrastructure status, and API version. Identical to GET /api/v1/health (the only public endpoint that does not require authentication). When to use it: at the start of a long task, or when a tool starts returning errors and the agent wants to differentiate “Theo is down” from “my prompt was bad”. 
{
  "status": "healthy",
  "version": "2026-03-28",
  "providers": {
    "theo-core": { "status": "healthy", "latencyMs": 42 },
    "theo-vision": { "status": "healthy", "latencyMs": 88 },
    "theo-search": { "status": "healthy", "latencyMs": 130 }
  },
  "infrastructure": {
    "database": { "status": "healthy", "latencyMs": 3 },
    "redis": { "status": "healthy", "latencyMs": 1 }
  }
}
Backed by theo.health() → GET /api/v1/health.

​
Error responses

If the underlying API call fails (network drop, expired key, etc.), the resource returns: 
Error reading theo://models: <fetch error>
with mimeType: "text/plain" instead of JSON. The agent can either retry or fall back to the matching tool (e.g. theo_status instead of theo://health).

​
How an IDE agent uses these

A typical Theo-aware agent prompt loop:
  1. On boot, pull theo://health to confirm engines are up.
  2. Pull theo://skills/installed to learn what domain knowledge is already loaded.
  3. Optionally pull theo://models so it knows the names of the engines it can ask for.
  4. Then start invoking tools (theo_complete, theo_code, …) for real work.
You can encode that loop in .theo/RULES.md (generated by theo init) so every agent in the workspace follows it.