Consumer truth as a tool call.

Pick your integration.

MCP lets an AI assistant or agent (Claude, Cursor, VS Code and other MCP clients) call ARIA as a tool, with each user signing in to their own account. The API is for integrating ARIA directly into your own applications and backends.

Quick start: ARIA MCP

ARIA runs as a remote Model Context Protocol (MCP) server. Add one URL to Claude, VS Code, Cursor or any other MCP client, sign in with your Convosight account, and your assistant can call ARIA for consumer intelligence.

1. Get accessThe server URL is https://aria-mcp.convosight.com/sse. Access is on request: email reachus@convosight.com.
2. Add it to your clientOne remote server, over Streamable HTTP. Pick your client below.
3. Sign in with your Convosight accountYour client opens a standard OAuth 2.1 sign-in the first time. No API keys or client secret to paste.
4. Ask in plain languagePass the question as the user asked it. ARIA researches it live, usually in 2–3 minutes.

# Claude Code
claude mcp add --transport http aria https://aria-mcp.convosight.com/sse

One tool: ask ARIA.

ARIA MCP exposes a single tool, ask_aria_text. It takes a question in plain language and returns ARIA's answer as plain-text prose, so it works in any client, including ones without a rich UI.

ARIA researches live. Give it time.

Each call blocks until ARIA finishes researching. That usually takes 2–3 minutes and can take up to 15. Set your agent's tool-call timeout, and the timeout on anything proxying the request, well above that.

Optional: show progress. Instead of waiting on a silent connection, your client can opt in to status updates. Add a progressToken of your choice (any value that's unique to that call) to the request's _meta. The server then streams progress notifications on the same response, ahead of the final answer. Leave it out and you simply get the final answer.

// tools/call with an optional progress token
{
  "method": "tools/call",
  "params": {
    "name": "ask_aria_text",
    "arguments": {
      "question": "Which hair care concerns are rising among USA consumers in the last 4 weeks?"
    },
    "_meta": { "progressToken": "<any-unique-value>" }
  }
}

Connecting a custom MCP client

Off-the-shelf clients like Claude, VS Code and Cursor handle sign-in for you. If you're wiring ARIA into your own agent or app, here's what to sort out first.

1. Request your connection detailsEmail reachus@convosight.com. We'll share your MCP URL and the OAuth client details for your app.
2. Send us your redirect URI(s)The callback URL(s) your app uses after sign-in, so we can register your app.
3. Auto-discover the OAuth endpointsUse the server's standard OAuth metadata to find the authorize and token endpoints. Don't hardcode them.
4. Allow long-running callsSet tool-call and proxy timeouts well above 15 minutes, and opt in to progress updates if you want a live status.
5. Thread follow-upsKeep the session_id from each answer and send it with the next question.

Errors and timeouts

ARIA doesn't retry automatically after a timeout or a temporary failure. If you want retries, re-issue the call from your side. Still stuck? Email reachus@convosight.com.

Quick start: Persona MCP

Persona turns social data into evidence-grounded consumer twins. With Persona MCP, you can talk to a Persona from any MCP-compatible assistant and pressure-test claims, concepts and messaging without switching tools.

# Claude Code
claude mcp add --transport http persona <your-persona-mcp-url>

Discover with ARIA. Validate with Persona.

Take an ARIA insight straight to a Persona and push back on it. Add both servers to the same client and your assistant can call either one.

// One client, both Convosight servers
{
  "mcpServers": {
    "aria": {
      "url": "https://aria-mcp.convosight.com/sse"
    },
    "persona": {
      "url": "<your-persona-mcp-url>"
    }
  }
}

Build ARIA into your own product.

The ARIA API lets you integrate ARIA's consumer intelligence directly into your apps, dashboards, workflows and agents. Call ARIA from your own backend, internal tools or agent framework. The same ARIA behind our app, ChatGPT and MCP.

It works over plain HTTP and it's asynchronous: you send a question, get a session_id back straight away, then poll until the answer is ready.

How it works

1. AskPOST · questionSend your question. You get 202 Accepted and a session_id.
2. PollGET …/{session_id}Every 3–5 seconds while status is in_progress.
3. Read the answerdone · errordone returns the answer as plain text. error returns a message, and it's safe to ask again.
4. Follow upPOST + session_idOnce the turn is done, ask again with the same session_id and ARIA keeps the context.

Authentication

Send your team API key as the raw value of the Authorization header on every request. Don't add a Bearer prefix. Keys can be deactivated or expire; either one returns a 401.

Authorization: <YOUR_TEAM_API_KEY>
Content-Type: application/json

Endpoints

Both endpoints sit under your team's base URL, shown here as <aria-api-base-url>. You get it with your API access.

Request body (POST)

Status values (GET)

Polling client examples

Each example asks a question, polls until it's done, then asks a follow-up in the same session.

# 1. Configure once (server-side; never ship the key to a browser)
export ARIA_API_BASE_URL="<aria-api-base-url>"
export ARIA_API_KEY="<YOUR_TEAM_API_KEY>"

# 2. Ask a question -> 202 Accepted + a session_id
curl -s -X POST "$ARIA_API_BASE_URL" \
  -H "Authorization: $ARIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How did our engagement trend last month?"}'
# { "session_id": 12345 }

# 3. Poll every 3-5 s until status is done or error (~5 min max)
SESSION_ID=12345
for i in $(seq 1 75); do
  sleep 4
  RES=$(curl -s "$ARIA_API_BASE_URL/$SESSION_ID" -H "Authorization: $ARIA_API_KEY")
  STATUS=$(echo "$RES" | jq -r .status)
  if [ "$STATUS" != "in_progress" ]; then break; fi
done
echo "$RES" | jq -r 'if .status == "done" then .answer else .error end'

# 4. Follow up in the same conversation (after the last turn is done)
curl -s -X POST "$ARIA_API_BASE_URL" \
  -H "Authorization: $ARIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Which platform drove most of it?", "session_id": 12345}'

Want to offer ARIA to your customers inside a product you sell? That's a partnership. Talk to us.

Error codes

Limits and behaviour

Best practices

1. Keep the API key server-sideStore it in a secrets manager. Never ship it in browser or mobile code.
2. Reuse the session_id for follow-upsSo ARIA keeps the conversational context.
3. Retry 429s with backoffA 429 only means you polled too fast. Wait, then poll again.
4. Don't retry 400 quota errorsThey won't succeed until your next quota period starts.

Plain-text answers, ready for your UI.

Over both MCP and the API, answers are plain text, so you decide how they render. The ARIA API returns the answer text only, without source links. confirm whether MCP answers include links to the source posts, as the public MCP docs say

Data