> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stack MCP

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

<Note>
  Documents Stack **`0.2.0-dev.20260701.1`**. Goal monitor tools documented in the
  [2026-07-01 changelog entry](/stack/changelog).
</Note>

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):**

```bash theme={null}
./bin/stack-mcp
```

**HTTP (when stackd is healthy):**

```text theme={null}
http://127.0.0.1:8792/mcp
```

Stack registers MCP on Codex turns from the Agent pane when configured. See [stackd](/stack/stackd).

For hosted Managed Research without the Stack cockpit, see
[MCP Quickstart](/managed-research/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`, …) |

Used by the sidecar monitor in [Goal mode](/stack/goal-mode).

## 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 inference](/stack/inference) — Nemotron aux endpoint
* [Optimizers](/stack/optimizers) — local GEPA
* [Cockpit controls](/stack/cockpit) — staging remote actions from the TUI