MCP Quickstart

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

Connect

Codex
Claude Code
Local stdio

codex mcp add managed-research --url https://api.usesynth.ai/mcp

claude mcp add --transport http managed-research https://api.usesynth.ai/mcp

uv tool install "synth-ai[research]==0.13.0"
synth-ai-managed-research-mcp

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:

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:

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.

{
  "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:

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:

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

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

Getting Started

Managed Research

Stack

Research Factory

Prompt Optimization

Infrastructure

SDK Reference

Research API

Reference

Cookbooks

Connect

Smoke test

Start a one-off run

Start a project-scoped run

Inspect evidence

Common launch failures

​Connect

​Smoke test

​Start a one-off run

​Start a project-scoped run

​Inspect evidence

​Common launch failures

Connect

Smoke test

Start a one-off run

Start a project-scoped run

Inspect evidence

Common launch failures