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

​
Connect

codex mcp add managed-research --url https://api.usesynth.ai/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_project
  • smr_add_project_repo
  • 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_actor_status
  • smr_search_project_logs
  • smr_list_artifacts
  • smr_get_artifact_content
  • smr_get_usage

​
Common launch failures

SymptomWhat to check
Auth failureSYNTH_API_KEY is missing or scoped to the wrong workspace.
Preflight denialRead the smr_get_launch_preflight blockers before starting runtime.
Unsupported harness/modelCheck Models and Harnesses.
Unsupported reasoning effortReasoning effort is model-specific and Codex-only today.
Provider unavailableUse openrouter for public examples; backend preflight is authoritative.
Budget exceededCheck Usage and Budgets.
Launch denials are MCP tool errors, not success payloads with embedded error fields.