Hey Juno

How do you run customer research from your own tools and AI agents?

By Hey Juno · Published · Updated

You can run customer research from your own tools by connecting them to Juno, the AI researcher from Hey Juno, through its REST API, its hosted Model Context Protocol (MCP) server or the Agent2Agent (A2A) protocol. Your product, CRM or AI agent briefs Juno, and Juno does the research. The sensible set-up keeps a person in charge of two moments: deciding when real participants are invited, and reading what was found.

This guide explains when that makes sense, what each connection lets you do, how credentials and permissions work, and what good practice looks like. It is a plain-language overview. The full technical detail is in the Juno documentation.

When starting studies from your own tools makes sense

Most customers use the Juno app directly, and that is the right place to start. Connecting your own tools starts to pay off when research is a recurring part of another workflow:

  • From your product. A study opens when something happens, such as a customer cancelling, finishing onboarding or reaching a milestone, and the person gets an invite link carrying what you already know about them.

  • From your CRM. A team picks a segment, and each person receives a link that is matched back to their record when the interview finishes.

  • From an AI agent or assistant. A colleague asks an assistant such as Claude, ChatGPT or OpenAI Codex to draft a study, and it calls Juno on their behalf.

  • From an internal tool or pipeline. Studies, links and exports run alongside the systems your team already uses.

If you run a handful of studies a year, the app is simpler. Connect your tools when you would otherwise be copying the same information between systems by hand. For the research itself, see what AI-moderated qualitative research is and how qualitative interviews run at scale.

What the REST API, MCP and A2A let you do

All three expose the same core intents, so the choice depends on who or what is doing the calling.

  • REST API. Use it when backend code, an internal tool or a pipeline calls Juno directly. It has a public OpenAPI specification covering studies, simulations, participant links, interviews and exports.

  • Hosted MCP server. Use it when an AI assistant is doing the driving. MCP lets an assistant call Juno through tools, and the tools follow the same study lifecycle as the app. The Juno server offers 15 tools. Claude, ChatGPT, OpenAI Codex or any MCP client can connect. The protocol is described at modelcontextprotocol.io.

  • A2A. Use it when your own agent should give Juno plain-language instructions. Juno responds as an agent. A2A is text only, so documents are uploaded over REST first.

In practical terms, you can:

  1. Brief Juno in plain language. The brief is a sentence or two on the research goal, who the participants are and what you want to learn. Juno creates the study in Test mode.

  2. Upload documents as context and attach them to a study.

  3. Update the study with further instructions.

  4. Rehearse the interview with a simulation.

  5. Set the study live, when you are ready for real participants.

  6. Get the study's durable invite link, or create participant links that carry context about the people they are for.

  7. List and read interviews as they finish.

  8. Export Live-mode interviews as CSV.

Slow work, such as creating a study, running a simulation or an export, runs in the background. Your tool gets a job to check, not a fixed wait. Repeat requests can be made safe with an idempotency key, so a retry does not do the work twice.

Credentials and permissions

There are two kinds of credential.

API keys belong to an organisation. Any member can create one in the Juno app under Settings, then Developer. You name it, choose its permissions, choose the test or live data environment and choose an expiry. The secret is shown once and only a hash is kept, so store it straight away in a secret manager. A key works for REST, MCP and A2A when it carries the right permissions. Use a key for your own backend.

OAuth is for apps that other people connect to their own workspace. The person signs in to Juno, chooses a workspace, chooses which permissions to grant and can disconnect later. Your app never sees a password or an API key. Juno supports OAuth 2.1 with discovery, dynamic client registration and PKCE. REST and MCP accept the resulting token. A2A does not: it needs an API key.

Every credential carries a set of permissions, called scopes. Seven scopes cover the whole surface. Writing a study and going live are separate scopes, and the A2A scope is available to API keys only. OAuth offers six of the seven. Grant only what the integration needs. Before you build against a credential, call whoami. It tells you which organisation, data environment and permissions the credential resolves to.

One point trips people up. The jsk_test_ and jsk_live_ prefix on a key sets its data environment. It is not the same thing as a study's Test mode and Live mode, which are controlled separately through the study lifecycle. Rate limits are counted against the credential, and a request over the limit gets a 429 with a Retry-After header; the current limits are in the developer documentation.

Keeping a person in the loop

Automation is useful. Handing it the two decisions that carry consequences is not.

Launching a study. In Juno, a study always starts in Test mode, and going live is a separate step with its own permission. That separation is deliberate: Juno creates and updates the study, but a person chooses when real participants take part. Live interviews use credits. Do not give an unattended agent the go-live permission unless you have decided that is acceptable. A safer pattern is that your tool drafts the study and a person reviews it and presses Go live.

Reading findings. An agent can fetch interview records and start exports, but it should not be the last reader. Findings are claims that should be checked against the quotes behind them. Have a person check the findings before they feed a decision or a customer message. The same applies if an agent summarises results for you: treat the summary as a pointer back to the evidence, not the evidence.

The MCP specification says there should always be a human in the loop with the ability to deny tool invocations. If your assistant offers a confirmation step before it calls a tool, keep it switched on.

Good practice

  • Rehearse first. Run a simulated interview before anything goes live. Juno plays the interviewer and a synthetic participant answers. It uses no credits and produces no analysis, and it is for rehearsal only: simulations are never research data and never findings. For the principle, see real participants versus synthetic respondents.

  • Keep invite links scoped. Use a participant link per group, or per person when the context identifies one individual. A per-person link belongs to whoever opens it first, so send it only to the person it is for.

  • Use the least permission. Give a reporting tool read scopes only. Give a drafting agent write scopes but not go-live.

  • Set expiries and rotate. Choose an expiry for keys, revoke ones you no longer use, and refresh OAuth tokens from one place only.

  • Use a test key first. Build against the test data environment, then switch.

  • Brief well. An agent that sends a vague brief gets a vague study. See how to write a research brief.

  • Handle personal data deliberately. Context you attach to links can include customer details. Send only what the study needs, and check with your own privacy team. See PII in customer research and security for AI research platforms.

Where this doesn't apply

  • One-off studies. The app is quicker than building an integration.

  • Teams without anyone to review. If no one will read findings or approve launches, automating more of the process adds risk, not value.

  • Fully unattended launches. This guide assumes a person decides when real participants are invited.

  • Anything beyond the documented surface. If it is not in the documents, do not assume it exists.

Frequently asked questions

Do I need to write code to use Juno from an AI assistant?

Not necessarily. You add the hosted server to your MCP client's configuration and send an API key or an OAuth access token as a bearer token. Check your client's own documentation for how it does that.

Should I use an API key or OAuth?

Use an API key for your own backend. Use OAuth when other people connect your app to their own Juno workspace, so they approve the permissions and can disconnect later.

Can an agent launch a study without a person?

Only if you give it the go-live permission. We suggest leaving that step to a person, so that real participants are invited only when someone has reviewed the study.

Can I get transcripts through MCP?

The interview list does not carry transcripts and answers. Start a Live-mode CSV export with the start_export tool, then fetch the finished file over REST, because there is no MCP download tool.