Skip to main content

​
MCP is the supported interface

Managed Research currently supports external automation and agent integrations through MCP only.
  • Supported: Managed Research MCP tools + UI.
  • Not supported as an external integration contract: direct SMR REST endpoint wiring.

​
1) Install the MCP server

Install synth-ai and use the bundled SMR MCP server: 
uv tool install synth-ai
MCP command: 
synth-ai-mcp-managed-research

​
2) Configure auth

Set your API key: 
export SYNTH_API_KEY="sk_..."
Optional backend override: 
export SYNTH_BACKEND_URL="https://api.usesynth.ai"
The MCP server uses these defaults automatically. You can also pass api_key and backend_base per tool call when needed.

​
3) Claude Code setup

In Claude Code MCP settings, add a server with: 
{
  "mcpServers": {
    "synth-managed-research": {
      "command": "synth-ai-mcp-managed-research",
      "env": {
        "SYNTH_API_KEY": "sk_..."
      }
    }
  }
}
Use environment variables for auth:
  • SYNTH_API_KEY (required)
  • SYNTH_BACKEND_URL (optional override)

​
4) Codex setup

In Codex MCP settings/config, add the same server definition: 
{
  "mcpServers": {
    "synth-managed-research": {
      "command": "synth-ai-mcp-managed-research",
      "env": {
        "SYNTH_API_KEY": "sk_..."
      }
    }
  }
}
Use environment variables for auth:
  • SYNTH_API_KEY (required)
  • SYNTH_BACKEND_URL (optional override)

​
5) Cursor setup

Use the same server command in Cursor MCP config: 
{
  "mcpServers": {
    "synth-managed-research": {
      "command": "synth-ai-mcp-managed-research",
      "env": {
        "SYNTH_API_KEY": "sk_..."
      }
    }
  }
}

​
6) Cline setup

For Cline, register the Managed Research MCP server with: 
{
  "mcpServers": {
    "synth-managed-research": {
      "command": "synth-ai-mcp-managed-research",
      "env": {
        "SYNTH_API_KEY": "sk_..."
      }
    }
  }
}

​
7) Continue setup

For Continue MCP/server config, use: 
{
  "mcpServers": {
    "synth-managed-research": {
      "command": "synth-ai-mcp-managed-research",
      "env": {
        "SYNTH_API_KEY": "sk_..."
      }
    }
  }
}

​
8) Smoke test in under 1 minute

Run these tools in order:
  1. smr_list_projects
  2. smr_create_project
  3. smr_get_project_status
  4. smr_trigger_run
  5. smr_get_run
If smr_list_projects returns successfully, auth and connectivity are working. smr_trigger_run and smr_trigger_data_factory now require a work_mode argument on every launch:
  • open_ended_discovery for exploratory, discovery-oriented work
  • directed_effort for scoped, outcome-directed execution
Quick local launch checks:
  • synth-ai-mcp-managed-research
  • python -m managed_research.mcp

​
9) Outcome-first workflows

​
Lease a coding sandbox and return URL/credentials

  • smr_create_project
  • smr_add_project_repo
  • smr_trigger_run
  • smr_get_actor_status
  • Return mcp_host, worker identity, and runtime status fields to the caller.

​
Run tests/evals in pooled environments and summarize failures

  • smr_get_pool_context
  • smr_trigger_run
  • smr_get_run
  • smr_search_project_logs
  • smr_get_usage

​
Tail logs/traces and pinpoint regressions

  • smr_search_project_logs
  • smr_get_actor_status
  • smr_list_runs
  • smr_get_run

​
10) Core tool recipes (Claude Code + Codex)

​
Create and run a project

  • smr_create_project
  • smr_add_project_repo
  • smr_trigger_run
  • smr_get_run
  • smr_list_runs

​
Data factory path

  • smr_get_starting_data_upload_urls
  • smr_upload_starting_data
  • smr_trigger_data_factory
  • smr_data_factory_finalize
  • smr_data_factory_publish

​
Runtime + operations

  • smr_get_project_status
  • smr_get_actor_status
  • smr_control_actor
  • smr_get_usage
  • smr_search_project_logs

​
11) Adoption defaults for both clients

  • Set agent_kind explicitly in run-trigger flows (codex or claude) so behavior is deterministic across teams.
  • Start with read/inspect tools first (smr_list_projects, smr_get_project_status, smr_get_usage) before enabling mutation workflows.
  • Keep one shared team MCP config template and only vary SYNTH_API_KEY/SYNTH_BACKEND_URL per environment.

​
12) Troubleshooting

  • Auth failures: verify SYNTH_API_KEY is set and active.
  • Wrong environment: set SYNTH_BACKEND_URL explicitly for dev/staging.
  • Tool not found: restart MCP client after updating managed-research.
  • No runs appearing: verify project onboarding/status with smr_get_project_status.

​
Security notes

  • Treat your Synth API key as a secret; never commit it.
  • Prefer least-privilege/project-scoped operational workflows.
  • Use MCP as the control boundary; avoid custom direct REST clients for SMR.