Stack MCP

Give Codex typed access to local optimizers and hosted Synth live ops.

Documents Stack 0.2.0-dev.20260703.2. Lights, gardener, and durable meta-thread tools are documented in the 2026-07-03 changelog entry.

Stack exposes a Model Context Protocol (MCP) server so Codex (and other agents) can operate Synth through typed tools instead of scraping persistence or guessing API routes.

Run the server

Stdio (default for Codex in Stack):

./bin/stack-mcp

HTTP (when stackd is healthy):

http://127.0.0.1:8792/mcp

Stack registers MCP on Codex turns from the Agent pane when configured. See stackd.

For hosted Managed Research without the Stack cockpit, see MCP Quickstart.

Start here: stack_status

Codex should call stack_status first. It returns bridge mode, environment, local optimizer state, remote SMR/Factory snapshot, hosted optimizer jobs, auth readiness, and suggested next actions.

Then choose local-only or remote-only mode in the TUI (x) before live actions so tools match the intended surface.

Live operations tools

Tool	Purpose
stack_list_live_smrs	Recent live SMR runs
stack_list_factories	Research Factories
stack_list_hosted_optimizer_runs	Hosted optimizer jobs
stack_live_status	Account + live snapshot
stack_message_live_run	Operator message to a run
stack_message_factory_project	Message via Factory route
stack_control_live_run	Pause / resume / stop
stack_cancel_hosted_optimizer	Cancel hosted job
stack_preview_hosted_optimizer_artifact	Bounded artifact preview
stack_download_hosted_optimizer_artifact	Download to Stack state
stack_preview_run_output	Preview WorkProduct / artifact
stack_download_run_output	Download via owner routes
stack_list_saved_downloads	Local download history
stack_upload_run_file	Upload file to a live run

Downloads save under .stack/downloads/<environment>/<run-id>/.

Monitor and goal tools

Tool	Purpose
stack_monitor_goal_status	Post operator-visible goal/monitor updates (headline, for_human, …)
stack_lights_thread_view	Open Lights, select/filter threads, and mark threads viewed or unviewed
stack_worker_thread_create	Create a durable Stack-visible worker thread, optionally with a goal
stack_meta_thread_create	Bind an existing Stack session/thread to a durable meta-thread
stack_meta_thread_update_goal	Assign or update the goal on an existing durable meta-thread

Used by the sidecar monitor and gardener in Goal mode. Thread/goal creation must go through these owner tools; agents should not claim durable thread creation from local transcript edits or raw persistence writes.

Skills and guidance

Tool	Purpose
stack_skills_list / stack_skills_read / stack_skills_search	Stack skill catalog
stack_guidance_list / stack_search_guidance / stack_guidance_read	Searchable guidance index
stack_skills_push_context	Visible monitor→primary skill context push

Bundled skills install to ~/.stack/skills/ on make install. Stack mirrors them into the workspace .codex/skills/ for Codex discovery and never writes to ~/.codex/skills.

Codex skills to load

Load in this order when helping a Stack user:

1. synth-stack-productivity — OSS + hosted map
2. stack-local-setup — install, auth, local GEPA
3. synth-via-stack — containers and optimizers
4. stack-agent-bridge — live MCP operator workflow
5. oss-gepa / gepa — when working with synth-optimizers

Skills ship in the Stack repo under .codex/skills/.

Rules of thumb

• Use owner routes and MCP tools — do not bypass Stack to hit backend persistence.
• Preview before download on large artifacts.
• Never paste API keys into prompts or logs.
• Start with stack_status, narrow to local or remote, then act.

Next

• Hosted ops — SMR, Factories, and remote sync
• Hosted inference — free aux and billed GLM
• Optimizers — local GEPA
• Cockpit controls — staging remote actions from the TUI