MCP and local API

Coldtea runs a local API beside the desktop app so agent panes can work with Coldtea without scraping terminal output. The same server hosts Coldtea's MCP endpoint, which gives launched agents a set of tools for the workspace around the terminal.

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 on an ephemeral port chosen at startup. It is loopback only, so it is reachable from your machine and not from the network. Coldtea uses it for desktop-to-agent coordination.

Its routes cover:

• A health check.
• Agent and shell lifecycle hook events.
• Agent artifact events.
• The desktop auth callback handoff.
• Coldtea's MCP endpoint at POST /mcp.

The exact route set and tool set can vary by build and session. Do not hardcode the port; it is not fixed.

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.

MCP tool catalog

Coldtea's MCP tools let an agent act on the workspace: the terminal, the in-app browser, tasks, QA runs, labels, teams, and artifacts. Tools split into two groups: local tools run in the desktop app with no sign-in, and TeaHouse tools need you signed in to Coldtea because they reach the backend.

Terminal

Local. Inspect and drive terminal panes instead of asking the user to paste output.

• list_terminals: list the terminal panes visible to this pane; each alias is a stable handle.
• open_terminal: open a visible terminal pane or tab, running a shell, a command, or an agent.
• read_terminal: read retained content from a pane, including scrollback.
• search_terminal: search a pane's retained content and return matching lines with context.
• get_visible_terminal_state: get a pane's exact visible screen now, useful for prompts and TUIs.
• send_terminal_message: send text to a pane once the pane is ready.

Pane labels

Local, and gated behind the auto pane-labeling setting. Use these only for ad-hoc work that is not a Coldtea task; task work labels itself through task_start_work.

• set_pane_label: set or update the current pane's short work label.
• clear_pane_label: clear the current pane's label when the user asks.

Browser and annotations

Local. These drive the same in-app browser the user sees and annotates, never a headless session.

• browser_open, browser_navigate, browser_back, browser_forward, browser_reload: open and move around the in-app browser.
• browser_snapshot: read the page: URL, title, visible text, and interactable elements with stable ids.
• browser_screenshot: capture a PNG of the visible viewport.
• browser_click, browser_type, browser_press_key, browser_scroll: interact with the page by element id or coordinates.
• browser_wait_for: wait until text, a URL match, a selector, or load completes.
• browser_annotations_list, browser_annotation_focus, browser_annotation_resolve: list the user's page annotations, scroll to one, and mark it resolved once acted on.

Tasks, plans, logs, and workspaces

TeaHouse. These read and write Coldtea tasks and the plans and logs attached to them.

• task_workspaces_list: list accessible TeaHouses, teams, and workflow states.
• task_list, task_get: list and read tasks and subtasks.
• task_create, task_update, task_patch_description, task_delete: create and change tasks.
• task_start_work: begin working on a task; this owns the pane label.
• task_log_session, task_read_session_logs, task_read_session_log: append and read session logs.
• task_log_implementation_plan, task_read_implementation_plans, task_read_implementation_plan: log and read implementation plans. Plans are immutable versions; the latest is current.

QA (Matcha)

TeaHouse. These run and read Matcha QA. Runs cost money, so agents pass a client request id and reuse it on retry.

• qa_run_start, qa_run_stop: start a run against a URL with a user path or a saved test, and stop one still running.
• qa_run_list, qa_run_get: list run metadata and read one full run with its steps and verdict.
• qa_run_share: mint a public report link for one run.
• qa_group_create, qa_group_list, qa_group_run_all: manage QA groups and run every runnable test in a group.
• qa_test_list, qa_test_delete: list and delete saved tests.
• qa_test_user_create, qa_test_user_list: manage the web test users a run can sign in as. Credentials are stored as secrets and never echoed back.

Labels

TeaHouse.

• label_list, label_get: list a team's labels and read one in full.
• label_create: create a team label for use on tasks.

Agent teams

• create_agent_team (TeaHouse): create or update a reusable agent team with two to four named roles.
• launch_agent_team (local): launch a saved team, opening each role in its own pane.

Artifacts

TeaHouse.

• artifact_create: publish an HTML page as a shareable Coldtea artifact and get back a public URL.
• artifact_list: list the artifacts you published, newest first.

Internal-only guide tools

Coldtea's first-run guide uses a small set of tools (guide_highlight and guide_done) to spotlight UI and mark the tour complete. They are registered only inside a guide session and are not part of the public tool surface. See onboarding and tours.

Why a tool may be missing

Some tools are conditional, so tools/list is not a fixed catalog. Check:

• The agent was launched from Coldtea, not from an unrelated terminal.
• The pane belongs to the expected project or worktree.
• You are signed in if the tool needs TeaHouse or task access.
• Pane-label tools are enabled only when auto pane-labeling is on.
• 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 prints 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 matrix or context.