> ## 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.

# MCP Quickstart

> Connect a hosted MCP client, start a Managed Research run, and inspect evidence.

Managed Research MCP is the agent-client interface for starting, steering, and inspecting runs from Codex, Claude Code, Cursor, and similar tools.

## Connect

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add managed-research --url https://api.usesynth.ai/mcp
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http managed-research https://api.usesynth.ai/mcp
    ```
  </Tab>

  <Tab title="Local stdio">
    ```bash theme={null}
    uv tool install "synth-ai[research]==0.13.0"
    synth-ai-managed-research-mcp
    ```
  </Tab>
</Tabs>

Set `SYNTH_API_KEY` in the environment or in your MCP client configuration. Use `SYNTH_BACKEND_URL` only when targeting a non-production backend.

## Smoke test

Ask your MCP client:

```text theme={null}
List my Managed Research projects.
```

The client should call `smr_list_projects`. An empty list means auth and connectivity are working.

## Start a one-off run

Ask your MCP client:

```text theme={null}
Start a one-off Managed Research run with host_kind daytona, work_mode directed_effort, provider openrouter, runbook lite, and this kickoff message:
"Inspect the repo, improve the target workflow, and explain the evidence."
```

The underlying MCP call is `smr_start_one_off_run` with `initial_runtime_messages`.

```json theme={null}
{
  "host_kind": "daytona",
  "work_mode": "directed_effort",
  "providers": [{"provider": "openrouter"}],
  "runbook": "lite",
  "initial_runtime_messages": [
    {
      "mode": "queue",
      "body": "Inspect the repo, improve the target workflow, and explain the evidence."
    }
  ]
}
```

## Start a project-scoped run

Use a project when the worker needs reusable repo bindings, files, datasets, credentials, notes, or budgets.

Ask your MCP client:

```text theme={null}
Create a Managed Research project for owner/repo, attach the GitHub repo, preflight a directed effort run on daytona with provider openrouter, then start it if preflight is clear.
```

Useful tools:

* `smr_create_runnable_project`
* `smr_attach_source_repo` (and GitHub setup tools as needed)
* `smr_prepare_project_setup`
* `smr_get_launch_preflight`
* `smr_trigger_run`

## Inspect evidence

Ask:

```text theme={null}
Show the run status, recent messages, actor status, artifacts, and usage.
```

Useful tools:

* `smr_get_run`
* `smr_get_run_execution`
* `smr_get_run_transcript`
* `smr_list_run_artifacts`
* `smr_get_artifact_content`
* `smr_list_run_actor_logs`
* `smr_get_run_usage`

## Common launch failures

| Symptom                      | What to check                                                             |
| ---------------------------- | ------------------------------------------------------------------------- |
| Auth failure                 | `SYNTH_API_KEY` is missing or scoped to the wrong workspace.              |
| Preflight denial             | Read the `smr_get_launch_preflight` blockers before starting runtime.     |
| Unsupported harness/model    | Check [Models and Harnesses](/managed-research/models-and-harnesses).     |
| Unsupported reasoning effort | Reasoning effort is model-specific and Codex-only today.                  |
| Provider unavailable         | Use `openrouter` for public examples; backend preflight is authoritative. |
| Budget exceeded              | Check [Usage and Budgets](/managed-research/usage).                       |

Launch denials are MCP tool errors, not success payloads with embedded error fields.