MCP and local API

Coldtea runs a local API beside the desktop app so agent panes can work with Coldtea without scraping terminal output.

Most users do not need to configure this by hand. It matters when you are debugging agent tools, local automation, pane inspection, or why a launched agent cannot see Coldtea task or terminal tools.

What the local API is

The local API listens on 127.0.0.1 using a runtime-selected port. Coldtea uses it for local desktop-to-agent coordination.

It can support routes for:

• Health checks.
• Agent lifecycle hook events.
• Supported agent artifact events.
• Desktop auth callback handoffs.
• Coldtea's MCP endpoint.

The exact route set and tool set can vary by build and session.

What agents receive

Agent sessions launched by Coldtea may receive session-scoped environment such as:

• COLDTEA_LOCAL_API_URL
• COLDTEA_MCP_URL
• COLDTEA_MCP_TOKEN

Those values let the agent reach the local MCP endpoint for that pane. Treat them like sensitive session data. Do not paste them into shared tasks, screenshots, or logs.

What MCP tools are for

Coldtea's MCP tools let agents interact with the workspace around the terminal.

Depending on session scope and feature flags, tools may include:

• Listing, reading, searching, opening, and messaging terminal panes.
• Setting or clearing pane labels.
• Reading and updating Coldtea tasks.
• Logging implementation plans and session notes.
• Reading Matcha QA runs where available.
• Reading or creating labels.

Agents should check which tools are actually available in the current session. A tool that exists in one pane may not be available in another.

When tools are missing

Check:

• The agent was launched from Coldtea, not from an unrelated terminal.
• The pane is connected to the right project or worktree.
• You are signed in if the tool needs TeaHouse or task access.
• The feature is enabled for your build and workspace.
• The agent's own config did not block Coldtea's session config.

For OpenCode, Coldtea adds a small managed plugin and session-scoped MCP config when the pane has the required Coldtea environment. User-owned OpenCode config is still respected. If a user config blocks automatic attachment, the wrapper should print a terminal diagnostic.

Safety boundary

The local API is for the desktop app and the agent processes Coldtea launches. It is not a public integration endpoint.

Keep local API URLs and MCP tokens private. If you need a repeatable external integration, use a documented team or API surface for that workflow instead of copying a live session token.

Next: agent setup or context.