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 runs on your machine only. It is not reachable from the network, and its port changes each time Coldtea starts, so there is nothing to hardcode or expose. Coldtea uses it to coordinate between the desktop app and the agents it launches, and it hosts the MCP endpoint those agents connect to.
What agents receive
Agent sessions launched by Coldtea may receive session-scoped environment such as:
COLDTEA_LOCAL_API_URLCOLDTEA_MCP_URLCOLDTEA_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. They split into two groups. Local tools act on the desktop app and need no sign-in. TeaHouse tools reach your shared workspace, so they need you signed in to Coldtea.
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. A QA run costs money, so a retried start is deduplicated rather than billed twice.
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: get a shareable report link for one run, readable without sign-in.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
list_agent_teams(TeaHouse): list saved teams in ateamsarray with their ids, role labels, and preferred agent ids.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.
Why a tool may be missing
Not every tool is available in every pane. 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.
- Auto pane labeling is on, if you are missing the pane-label tools.
- The agent's own config did not override the one Coldtea set for the session.
OpenCode is the one to watch here, because Coldtea attaches its tools through OpenCode's own config. Your OpenCode config still wins, so if it blocks the attachment, the pane prints a note saying so.
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.