Resources

In addition to tools (which are things your assistant can call), espctl also has resources — read-only URLs your assistant can fetch on demand. Resources are for “show me X” instead of “do X”.

There are 15 readable URLs (13 fixed plus 2 URI templates), in four groups.

Install resources — `install://*`

Self-documenting setup snippets for each AI tool. Ask your assistant to read any of these and it returns a copy-paste-ready config block, pre-filled with the actual paths on your machine.

URL	Returns
`install://overview`	Full setup guide with the env-var table and an explanation of plan-only vs remote build modes.
`install://claude-code`	A `.claude/settings.json` snippet for Claude Code.
`install://cursor`	A `.cursor/mcp.json` snippet for Cursor.
`install://claude-desktop`	A `claude_desktop_config.json` snippet for Claude Desktop.
`install://codex`	A `~/.codex/config.toml` snippet for Codex CLI.
`install://opencode`	An `opencode.json` snippet for OpenCode.

Tip: These are the same snippets that appear in each chapter of Part II — Client Setup, but pre-filled with the actual espctl path that espctl can detect on your machine.

Build server resources — `store://*`

Read-only views of what the build server has installed. The “store” lives on the build server, not on your computer.

URL	Returns
`store://versions`	The list of ESP-IDF versions on the build server (same data as the `store_versions` tool, but as a resource).
`store://manifest`	The full server manifest, including tool paths, checksums, and metadata.

Project resources — `project://*`

Read-only views of the current project (whichever folder espctl is set to look at).

URL	Returns
`project://config`	The contents of `.espctl.toml`.
`project://idf-version`	The contents of `.idf-version` (the per-project IDF pin file).
`project://sdkconfig`	The current `sdkconfig` (final settings after merging defaults).
`project://compile_commands`	The `compile_commands.json` from the most recent build, for IDE integration.

project://compile_commands is especially handy if you want clangd or any other code-intelligence tool to understand your project’s include paths.

Build resources — `build://*`

Live views of build state — log lines and output files. These exist because asking-over-and-over is wasteful when your assistant only needs to react to new data.

URL	Returns
`build://log/latest`	Log lines from the most recent build (any task).
`build://log/{task_id}`	Log lines for a specific build. Pushes new lines as they happen.
`build://artifacts/{target}`	The artifact list for a specific chip (same data as `list_artifacts`).

build://log/{task_id} is the preferred way to read live build output — it’s a streaming resource, so your assistant doesn’t have to keep asking. Most AI tools support both one-shot reads and live subscriptions on resources.

How to fetch a resource

The exact syntax depends on your AI tool. A typical request looks like:

Read the install://overview resource.

…or:

Subscribe to build://log/0abf...e2 and show me new lines.

Behind the scenes, your AI tool asks espctl for the resource. The response is markdown text or structured JSON, depending on which resource it is.

Resources vs tools — when to use which

You want to…	Use a…
…trigger an action with side effects	Tool
…read live state	Resource
…read state once	Either (resources are slightly cheaper for repeated reads)
…watch a value change over time	Resource (subscribe)

The line between the two can be fuzzy. As a rule: if it has side effects or takes arguments that change behavior, it’s a tool. If it just gives you a snapshot, it’s a resource.

ESP-IDF MCP — User Manual