Resources

In MCP, resources are read-only URIs an agent can pull for context without invoking a tool. @hitheo/mcp exposes three:

URI	Mime type	Description
`theo://models`	`application/json`	Available Theo models and their routing config
`theo://skills/installed`	`application/json`	Skills active on the current API key
`theo://health`	`application/json`	Live 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:

On boot, pull theo://health to confirm engines are up.
Pull theo://skills/installed to learn what domain knowledge is already loaded.
Optionally pull theo://models so it knows the names of the engines it can ask for.
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.

Getting Started

Quickstart

Core Concepts

Troubleshooting

Skills

Guides

MCP Server

Playground

Dashboard

Security & Compliance

Changelog

`theo://models`

`theo://skills/installed`

`theo://health`

Error responses

How an IDE agent uses these

​theo://models

​theo://skills/installed

​theo://health

​Error responses

​How an IDE agent uses these

`theo://models`

`theo://skills/installed`

`theo://health`

Error responses

How an IDE agent uses these