Reason8 MCP

Overview

Reason8 MCP exposes the same research specialist that powers reason8.io as a set of Model Context Protocol tools. Drop user research into any MCP-compatible agent loop — Claude Code asks Reason8, gets evidence-backed answers before you ship.

Quickstart

1. Generate a token in the portal Integrations page. Copy the r8_mcp_… value (shown once).

2. Install for your client — pick a tab in Install. For Claude Code:

   export REASON8_MCP_TOKEN="r8_mcp_xxx"
   claude mcp add --transport http reason8 https://api.reason8.io/mcp \
     --header "Authorization: Bearer $REASON8_MCP_TOKEN"

3. Run your first research call from inside the agent:

   Use reason8_research_start to investigate "What do mid-market CTOs
   say about evaluation gates before shipping AI features?"

4. Watch the run in the portal Recent agent runs section or by polling reason8_research_status.

Install

Supported today

export REASON8_MCP_TOKEN="r8_mcp_xxx"
claude mcp add --transport http reason8 https://api.reason8.io/mcp \
--header "Authorization: Bearer $REASON8_MCP_TOKEN"

Coming soon

ChatGPT. Requires OAuth 2.1 + Dynamic Client Registration. We're working on it. In the meantime, ChatGPT Custom GPTs can call Reason8's REST API directly — contact support if you need help wiring that.

Tools

reason8_research_start

Start a research workflow. Returns immediately with a run_id and events_url for SSE push updates.

Parameters:

Returns:

{
  "run_id": "r8run_abc...",
  "status": "running",
  "events_url": "https://api.reason8.io/api/v1/mcp/runs/r8run_abc/events"
}

curl:

curl -X POST https://api.reason8.io/mcp/tools/reason8_research_start \
  -H "Authorization: Bearer $REASON8_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "What do mid-market CTOs say about AI evaluation gates?"}'

TypeScript (via MCP SDK):

const result = await client.callTool({
  name: "reason8_research_start",
  arguments: { question: "..." },
});

Two ways to track progress

• Poll reason8_research_status every 5-15s — canonical, works in all MCP clients.
• Subscribe to the events_url SSE stream for push updates — opt-in, lower latency, useful for long-running narration.

reason8_research_status

Get the current state of a run. Returns progress_summary for agent narration.

Parameters: run_id (string, required).

Returns:

{
  "run_id": "r8run_abc",
  "status": "running | needs_input | brief_review | completed | failed | cancelled",
  "progress_summary": "Conducting 12 synthetic interviews…",
  "result": null
}

When status === "completed", result contains the final report.

reason8_research_continue

Send a follow-up to a run that's needs_input (clarification) or brief_review (approve/edit the research brief before paid methods run).

Parameters: run_id, message (string — for needs_input) OR approval: "approve" | "reject" + optional brief_edits.

reason8_research_cancel

Hard-stop a run.

Parameters: run_id.

Human-in-the-loop briefs

Reason8 may pause a run for two reasons: it needs more info from you (needs_input), or it wants you to approve the research brief before kicking off paid methods (brief_review).

start ──▶ needs_input ◄──▶ continue
              │
              ▼
        brief_review
              │
        continue(approve)
              ▼
          running ──▶ completed

When you see needs_input: call reason8_research_status to read the question, then reason8_research_continue with a message.

When you see brief_review: call reason8_research_status to read the brief, then reason8_research_continue with approval: "approve" (or "reject" + brief_edits to revise).

This is the only place a run will wait on you. Once approved, Reason8 runs to completion (or failure) without further prompts.

Authentication

All requests use HTTP Bearer auth with a token issued from the portal Integrations page.

Header: Authorization: Bearer r8_mcp_xxx

Scopes (all tokens have all three today):

• reason8_research:run — start, continue, cancel runs
• reason8_research:read — read run status
• reason8_research:cancel — cancel runs

Token format: r8_mcp_ + 16-char prefix + url-safe random tail. The full token is shown once in the portal — store it immediately.

Rotation: Revoke the old token and generate a new one. There's no overlap window — issue the new one, update your client, then revoke.

Rate limits & concurrency

All limits enforce on reason8_research_start. Status/continue/cancel are not rate-limited.

Hitting a limit returns 429 with a Retry-After header and an error message indicating which limit fired.

Troubleshooting

401 invalid token — Token is wrong or revoked. Generate a fresh one in the portal.

403 scope missing — Token doesn't have the required scope. All tokens today have all three scopes; if you see this, the token may be from a future scoped-token feature. Regenerate.

409 already running — A run with the same run_id is in flight. Call reason8_research_status first; only call start for a new question.

Run stuck in running — Active watchdog reclaims runs that go silent for 10+ minutes. If yours is older than that and still running, file a bug with the run_id — we'll investigate.

progress_summary missing in client — Your MCP client may not render structured progress. Use reason8_research_status directly and print the progress_summary field yourself.

FAQ

How is this different from the REST API? MCP exposes the same workflows as a set of agent tools with structured schemas — no client code to write. The REST API is for non-agent integrations (dashboards, scripts).

Can I use this without a paid account? Today, no — token issuance requires a workspace with billing configured. Contact support for evaluation access.

Are results cached? No. Each start triggers a fresh research run. Results are stored in your workspace's research history.

Can I tune the research specialist? Not via MCP today. Workspace-level prompt customization is on the roadmap.

Where do I report bugs? Email support@reason8.io with the run_id and a description.