MCP concepts

Connecting

Add the hosted server to your client configuration and send a credential as a bearer token. That is either an API key you created in the Juno app or an OAuth access token. The server is stateless and checks authority on every call. A key's data environment is separate from a study's Test mode or Live mode.

Call whoami first. It reports which organisation, data environment, and permissions the credential resolves to.

// Any MCP-native client — e.g. a .mcp.json / mcpServers entry
{
  "mcpServers": {
    "juno": {
      "type": "http",
      "url": "https://api.heyjuno.co/v1/mcp/",
      "headers": { "Authorization": "Bearer jsk_live_…" }
    }
  }
}

Tools

Fifteen tools cover the same ground as REST. Every tool rejects arguments it does not declare.

• whoami names the organisation, the data environment, and the permissions the credential carries.
• list_studies pages the organisation's studies, newest created first.
• get_study returns one study and its current brief.
• create_study briefs Juno in plain language and returns a job handle. Every new study starts in Test mode.
• refine_study gives Juno further instructions about an existing study and returns a job handle. The wire name refine_study means Update a study.
• get_authoring_status polls a create or update job until it is ready, then hands back the study and its brief.
• simulate_study rehearses the interview in Test mode and returns a job handle. get_simulation_status polls it and shows the transcript growing turn by turn.
• set_study_mode sets test, live, paused, or closed. Setting live performs Go live and requires studies:golive; the other values require studies:write.
• get_interview_link returns the study's durable invite link. It creates that link the first time it is asked, so it counts against the write budget, not the read budget.
• create_participant_link mints an invite link carrying context about the people it is for, and a note that steers the interviewer.
• list_interviews pages participant interviews and filters them by study and status. get_interview returns one. Neither returns the transcript.
• start_export begins a Live-mode CSV export and get_export_status polls it. There is no MCP download tool: fetch the finished file over REST.
• MCP has no upload tool. Upload the document over REST with POST /v1/api/files, then pass the returned file_id to create_study or refine_study.

Tool results

Each tools/call result contains REST-shaped JSON serialized in a text content block. Long-running tools return a job_id; poll the matching status tool until the job is ready.

Paging through lists

JSON-RPC has no response headers, so the paged tools put the cursor in the result instead. list_studies and list_interviews return next_cursor beside the rows. Pass it back as the cursor argument. It is null on the last page. The cursor value itself is the same on both transports.

{
  "interviews": [
    { "id": "…", "study_id": "…", "status": "completed", "is_complete": true }
  ],
  "next_cursor": "MjAyNi0wOS0xOFQwMDowMDowMFp8OWIyZjZjMWQ="
}

// Pass next_cursor back as the "cursor" argument. It is null on the last page.

Files

Files are context for Create study or Update study. MCP has no upload tool. Upload over REST with POST /v1/api/files as multipart form data, then pass the returned file_id to create_study or refine_study.

Export interviews

Start an export with start_export and watch it with get_export_status. There is no MCP download tool. Fetch the finished file over REST from GET /v1/api/exports/{job_id}/download.

Rate limits

Limits are counted against the credential, not your IP address, and they are split by cost. Reads get 120 requests a minute. Writes get 20 a minute. Over the limit you get 429 with a Retry-After header saying how many seconds to wait.

Every MCP call is a POST, so the read and write split cannot come from the HTTP method. Juno reads it from the tool instead. Eight tools count as reads: whoami, list_studies, get_study, get_authoring_status, get_simulation_status, list_interviews, get_interview, and get_export_status. Everything else counts as a write, including get_interview_link, which creates the link the first time it is asked. Polling a job is a read, so it is cheap to poll.

Full endpoint reference