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

# Resources

> The three read-only theo:// URIs your IDE agent can fetch via @hitheo/mcp.

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`](#theo-models)                     | `application/json` | Available Theo models and their routing config |
| [`theo://skills/installed`](#theo-skills-installed) | `application/json` | Skills active on the current API key           |
| [`theo://health`](#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.

<Note>
  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.)
</Note>

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

```json theme={null}
[
  {
    "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()`](/sdk-reference/client) → [`GET /api/v1/models`](/api-reference/models/list).

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

```json theme={null}
[
  {
    "id": "skill_a1b2c3",
    "slug": "deep-research",
    "name": "Deep Research",
    "description": "Multi-step research with citations",
    "version": "1.4.0"
  }
]
```

Backed by [`theo.skills("installed")`](/sdk-reference/skills) → [`GET /api/v1/skills?filter=installed`](/api-reference/skills/list).

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

```json theme={null}
{
  "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()`](/sdk-reference/client) → [`GET /api/v1/health`](/api-reference/health/check).

## Error responses

If the underlying API call fails (network drop, expired key, etc.), the resource returns:

```text theme={null}
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.