MCP Server & API

Endpoint

https://dashboard.deutero.ai/mcp

https://agents.deutero.ai/mcp serves the same server. Use https — an http:// URL will not connect.

The same API is also available as plain REST, documented at https://dashboard.deutero.ai/study-api/api/v1/docs. Every MCP tool is one REST route; the tool name is the route's name.

Authentication

Two methods work:

1. API key — send the header X-API-Key: <your key>. Best for IDEs and scripts.
2. OAuth — clients that support remote MCP authorization (for example the claude.ai connector) sign in with your Deutero account. Authorized clients appear under Connected Applications in Settings, where you can revoke them.

Getting an API key

1. Open Settings from the account menu (top right).
2. Scroll to Generate API Key.
3. Enter a Label — this is how you will recognize the key later.
4. Click Generate API Key.
5. Copy the key from the dialog. It is shown only once. The dialog also offers a ready-made DEUTERO_API_KEY=… line for shell use.

Keys are listed below the form with their label, prefix, status, creation date and last-used date. Use Disable to suspend a key, or delete it outright. Keys are scoped to your whole organization.

Configuration

Most clients take the same block. Keep the key in an environment variable rather than in a file you commit.

Claude Code

claude mcp add --transport http deutero https://dashboard.deutero.ai/mcp \
  --header "X-API-Key: $DEUTERO_API_KEY"

Cursor (~/.cursor/mcp.json), Windsurf (~/.windsurf/mcp.json), Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "deutero": {
      "url": "https://dashboard.deutero.ai/mcp",
      "headers": { "X-API-Key": "${env:DEUTERO_API_KEY}" }
    }
  }
}

Restart the client after editing its configuration.

What the tools cover

69 tools, grouped by what they touch. Names are exact.

Projects and studies

list_projects, create_project, get_project, update_project, create_study, list_studies, get_study, update_study

A study always lives in a project, so create or choose a project first. create_study takes project_id and name; everything else — survey_type (sociology, user_experience, customer_development, polling), research_question, objectives, target_population, model_tier, max_responses, voice_enabled, video_enabled, redirect_url — is optional and can be set later with update_study.

get_study is the one to call when you want to know where a study stands: it returns the configuration plus per-stage status (is the welcome message set, is screening enabled and how many questions, how many main questions) and the participation links.

Welcome and consent

get_welcome, set_welcome, list_welcome_translations, upsert_welcome_translation, delete_welcome_translation

Screening

get_screening, set_screening_settings, create_screening_question, update_screening_question, delete_screening_question, reorder_screening_questions

Screening questions are multiple choice. acceptable_options must be a subset of options, and lists who qualifies — anyone whose answer is not in that list is screened out.

Participant characteristics

get_characteristics, set_characteristics_settings, create_characteristic_question, update_characteristic_question, delete_characteristic_question, reorder_characteristic_questions

Questions

list_questions, create_question, update_question, delete_question, reorder_questions, validate_questions

create_question appends to the study's list. Set qtype explicitly, or let it be inferred from the fields you send (scale → scale, options → choices, slots → slots, expected_image → image upload, otherwise text).

{"question": "How satisfied are you?", "qtype": "scale",
 "scale": {"minScale": 1, "maxScale": 5, "minLabel": "Not at all", "maxLabel": "Very"}}

validate_questions runs the same review the dashboard's Validate button runs: clarity, leading or biased wording, and an ethics check.

Interview Flow (graph mode)

describe_graph_nodes, get_graph, check_graph, set_graph, patch_graph, import_questions_to_graph, activate_graph, deactivate_graph, get_flow_signals

See Interview Flow. Read describe_graph_nodes first — it returns the live config schema for every step type, so it cannot drift from what the validator accepts. get_flow_signals returns the per-step signing secrets for "Send a signal" steps, which is the only place they can be read.

Recruitment and embedding

get_recruitment, update_recruitment, list_embed_keys, create_embed_key, update_embed_key, get_embed_snippet

update_recruitment sets the short-link slug (unique across all studies), the response quota and the post-completion redirect.

Personas and simulation

list_personas, create_persona, update_persona, delete_persona, generate_personas, list_simulations, run_simulation, get_simulation, delete_simulation

run_simulation starts one run and returns immediately — poll get_simulation until it leaves running. One persona per call. Credits are reserved up front; a run that would exceed your balance is refused with 402 and costs nothing. Simulations are not available on Hobby.

Results

get_study_stats, list_interviews, find_interviews_by_external_id, get_interview, get_transcript, bulk_transcripts, search_transcripts, get_interview_fetches_and_signals

search_transcripts has three modes: string (full text, supports quoted phrases and -term), semantic (embedding similarity — finds the same idea in different words) and hybrid (default, fuses both).

find_interviews_by_external_id looks a person up by your id for them — the one the entry link's ?participant_id= or the embed metadata carried — and returns every attempt they made in full detail. list_interviews, bulk_transcripts and search_transcripts all take the same external_participant_id filter, and every interview, transcript and search hit carries the id back. See Recruiting participants.

Analysis

list_analyzable_questions, get_scale_responses, get_options_responses, run_clustering, get_optimal_clusters, get_latest_clustering

Call list_analyzable_questions with category set to text, scale or options to find out which questions support which analysis. run_clustering saves its result, so it also shows up on the study's Analyze page.

Webhooks

list_webhook_event_types, list_webhooks, create_webhook, update_webhook, rotate_webhook_secret, delete_webhook, list_webhook_deliveries

Organization-level event subscriptions — one endpoint covers every study. Read list_webhook_event_types first: an unknown event name is refused rather than stored. create_webhook returns the signing secret once; rotate_webhook_secret is the only way back if it is lost. See Webhooks.

Account

get_credit_balance, health_health_get

A typical agent session

1. list_projects / create_project        → pick where the study lives
2. create_study                          → returns study_id
3. create_question × N                   → build the interview
4. validate_questions                    → fix anything flagged
5. update_recruitment                    → set the share slug and quota
6. get_recruitment                       → give the participant link to the user
7. get_study_stats / list_interviews     → watch responses arrive
8. search_transcripts / run_clustering   → analyze

What MCP does not cover

These exist only in the dashboard:

• AI generation of study details, questions and welcome messages
• Thematic analysis (the multi-phase pipeline and its reports)
• Prolific recruitment
• Slack and Discord connectors
• Push notifications and billing
• Chat with Data

Troubleshooting

• 401 Unauthorized — the key is wrong, disabled or deleted. Regenerate it in Settings and check for stray whitespace.
• 402 — out of credits. Check Billing & Usage.
• 403 Upgrade required — the plan does not include the feature (for example simulations on Hobby). The message names the plan you need.
• 404 on /mcp/mcp — the URL is exactly /mcp, with no trailing path.
• Tools do not appear — restart the client after config changes, and check its MCP log.
• 409 on set_graph / patch_graph — someone edited the flow after you read it. Re-read get_graph and retry with the new graph_version.

---

Last updated: September 2026