Developers

Give any agent or app a mind to ask.

Connect once. Your software can ask a Mind Twin how a teammate will think, feel, say, and act, then keep that understanding current from the same workspace.

Start building

Hosted MCPPlain RESTStructured JSON

decision-roomconnected

YouAsk Maya's Mind Twin what would make her reject this rollout.

mind-twinchat_with_twin{ target: "[email protected]" }

Mind TwinI would reject a company-wide rollout without a contained pilot.

ThinkThe upside is clear. The risk is not.FeelInterested, but exposed.SayShow me one region working first.ActApprove a 30-day pilot.

workspace / acmeBearer key scoped

Choose your path ↓

Start with what you are building

One Mind Twin. Two ways in.

Both paths upload, check readiness, and ask. Choose who should make the call.

01MCP

Let the agent do it.

Your assistant chooses the right tool from plain language. No integration backend to build.

Claude Desktop, Claude Code, Cursor
Three clear tools
Readable answers by default

02REST

Make the call yourself.

Your server controls every request and receives structured JSON. No SDK required.

Node.js, Python, cURL, or any HTTP client
Four predictable endpoints
Think, Feel, Say, Act fields

The complete integration

Feed it. Wait once. Ask anything.

Three actions take a Mind Twin from a meeting to a decision-ready answer.

Feed

Add the meeting.

Send a dated transcript. VTT, SRT, text, and agent JSON all work.

upload_transcript

Ready

Check, then move on.

Learning runs in the background. Poll periodically until the status is ready.

get_status

Ask

Put judgment to work.

Ask about a past decision or a new situation. Get the answer and the reasoning around it.

chat_with_twin

Built in Re-uploading the same content and date is de-duplicated. It is not an error.

Path 01 · MCP

Your agent learns three verbs.

One hosted server gives an MCP-capable assistant everything it needs to keep a Mind Twin current and ask it questions.

Before you connect

Install Node.js once.

The command below runs through npx, which comes with Node.js.

MacHomebrew

brew install node

WindowsInstaller

nodejs.orgDownload

LinuxDebian / Ubuntu

sudo apt install nodejs

Verify

node --version
npx --version

Copy your key.

Open MCP Twin in the app. Your twin:chat key is already there.

Run one command.

The installer connects every supported MCP client it detects.

Open and verify.

If the tools do not appear, quit and reopen the client. Then ask which mind-twin tools it sees.

Terminal

npx -y add-mcp mcp-remote --name mind-twin \
  --args=https://mcp-twins.reasoner.com/mcp \
  --args=--header --args="Authorization: Bearer dev_YOUR_TWIN_CHAT_KEY" \
  --all -g -y

After install

Restart if the tools do not appear.

Some clients load new servers only when they open. If the three tools do not appear, fully quit and reopen the client, then ask which mind-twin tools it can see.

Serverhttps://mcp-twins.reasoner.com/mcp

Client namemind-twin

TransportStreamable HTTP

HostingManaged for you

PrerequisiteNode.js for npx

Agent integrations

Bring the same mind into the tools you already use.

Claude DesktopDesktop assistant

Ready

⌘

Claude CodeTerminal agent

Ready

↗

CursorAI code editor

Ready

Any MCP clientStreamable HTTP

Ready

The universal installer is the supported fast path. It detects compatible clients, adds the hosted server, and includes your Bearer header.

Call in. Result out.

Put judgment to work.

Ask one consequential question and request JSON when your agent needs structure.

chat_with_twin · call

{
  "name": "chat_with_twin",
  "arguments": {
    "message": "What would make you reject this rollout?",
    "target": "[email protected]",
    "format": "json"
  }
}

Example result

{
  "answer": "I would reject a company-wide rollout without a contained pilot.",
  "think": "The upside is clear. The implementation risk is not.",
  "feel": "Interested, but exposed if adoption fails.",
  "say": "Show me one region working first.",
  "act": "Approve a 30-day pilot with a stop point."
}

Good to knowformat defaults to text. Pass json for the structured answer, think, feel, say, and act object. Empty TFSA fields are omitted.

Path 02 · REST API

Your product gets the same mind, as JSON.

Use ordinary HTTPS from any server language. Every authenticated request carries the same Bearer key.

200 · application/json

One answer. The full human read.

answer is the complete response. say is the short spoken line. Any empty Think, Feel, Say, or Act field is omitted.

Node.js · POST /chat

const response = await fetch(
  "https://app.reasoner.com/api/twin-mcp/chat",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MINDTWINS_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "What would make you reject this rollout?",
      target: "[email protected]",
    }),
  },
);

if (!response.ok) {
  throw new Error(`MindTwins request failed: ${response.status}`);
}

const mindTwin = await response.json();

200 · Response

{
  "answer": "I would reject a company-wide rollout without a contained pilot.",
  "think": "The upside is clear. The implementation risk is not.",
  "feel": "Interested, but exposed if adoption fails.",
  "say": "Show me one region working first.",
  "act": "Approve a 30-day pilot with a stop point."
}

Base URLhttps://app.reasoner.com/api/twin-mcp

Mind Twin Teams

One workspace. Every teammate's judgment.

Add a teammate's email as target. The same chat, upload, and status action now goes to their team Mind Twin.

YouBearer keyIdentifies the caller

target

Workspace gateacme.comNever crosses workspaces

Team Mind TwinMayaOwner boundaries stay on

Ask Maya{ "target": "[email protected]" }

Workspace-scoped. A target can never resolve outside the key's workspace.
Team-only. Private Mind Twins cannot be reached through target.
Owner-controlled. Off-limits topics and private material stay withheld.
Team trust model. A Mind Twin Teams key can use all three actions on any team Mind Twin in that workspace without per-request owner approval.

Complete reference

Every action, in one view.

Scan the map first. Open an endpoint only when you need the exact fields.

Askchat_with_twin

message required, 1 to 10,000 · target optional · format defaults to text; pass json for structured TFSA

Feedupload_transcript

transcript and the real meeting date required · title, format, and target optional · limit 10,000,000 characters (roughly 10 MB)

Checkget_status

No fields for your own Mind Twin · target optional · no twin yet and ready + ingesting are expected conditions

Intent	MCP tool	REST endpoint	Returns
Ask a Mind Twin	`chat_with_twin`	POST`/chat`	Answer + TFSA
Add a meeting	`upload_transcript`	POST`/upload`	Processing state
Check readiness	`get_status`	GET`/me/status`	Status + progress
Check service	Not exposed	GET`/health`	Service status

POST/chatAsk a Mind Twin

Send one question. Omit target for your own Mind Twin.

messagestring · required · 1 to 10,000

The question to answer.

targetstring · optional

A teammate email. Requires twin:upload.

HTTP request

POST https://app.reasoner.com/api/twin-mcp/chat
Authorization: Bearer $MINDTWINS_KEY
Content-Type: application/json

{
  "message": "What would make you reject this rollout?",
  "target": "[email protected]"
}

200 · Response

{
  "answer": "I would reject a company-wide rollout without a contained pilot.",
  "think": "The upside is clear. The implementation risk is not.",
  "feel": "Interested, but exposed if adoption fails.",
  "say": "Show me one region working first.",
  "act": "Approve a 30-day pilot with a stop point."
}

POST/uploadAdd a meeting

Send up to 50 MB through REST. The MCP tool has a separate 10,000,000 characters (roughly 10 MB) limit.

transcriptstring · required

VTT, SRT, plain text, or agent JSON.

dateISO-8601 · required

Use the real meeting date. Never guess or default to today. Confirm each transcript separately.

titlestring · optional · max 500

A human-readable meeting name.

formatenum · optional

vtt, srt, text, or agent-json. Omit to auto-detect.

targetstring · optional

A teammate email. Requires twin:upload.

REST-only contextoptional

participants, duration, source, selfSpeaker, and segments. The MCP tool does not accept these fields.

HTTP request

POST https://app.reasoner.com/api/twin-mcp/upload
Authorization: Bearer $MINDTWINS_KEY
Content-Type: application/json

{
  "date": "2026-08-05",
  "title": "Pricing strategy call",
  "format": "vtt",
  "transcript": "WEBVTT\n\n00:00:01.000 --> 00:00:04.000\n...",
  "target": "[email protected]"
}

200 · Response

{
  "success": true,
  "data": {
    "status": "processing"
  }
}

GET/me/statusCheck readiness

Use [email protected] for a teammate. Poll periodically, not continuously.

no twin yetExpected before the first upload. REST returns 404. Upload a transcript to begin.buildingLearning is in progress. Poll periodically.readyThe Mind Twin is ready to answer.ready + ingestingIt stays chattable while a new transcript is folded in.failedThe build needs attention.

HTTP request

GET https://app.reasoner.com/api/twin-mcp/me/[email protected]
Authorization: Bearer $MINDTWINS_KEY

200 · Response

{
  "status": "building",
  "progress": 42
}

GET/healthCheck service liveness

No key required. Use it for a simple service liveness check.

HTTP request

GET https://app.reasoner.com/api/twin-mcp/health

200 · Response

{
  "status": "ok"
}

Authentication and boundaries

The key decides who you can ask.

Every authenticated request is tied to one caller and one workspace. The request never supplies a workspace id.

twin:chatEveryone

Your own Mind Twin.

Chat, upload, and status are all available for the key owner.

twin:uploadMind Twin Teams

Add the target field.

Use all three actions on a teammate's team Mind Twin inside the same workspace.

Provisioned for you Keys are created in the app. There is no public create-key endpoint.

Keep it server-side. Never ship a dev_ key in browser or mobile code.

Rotate on exposure. Regenerate in MCP Twin. The old key stops working immediately.

Use the narrow path. Drop target when you only need the key owner's Mind Twin.

Errors and retries

Know what failed. Know what to do.

Errors return JSON with error and code. Some responses also include message.

Status	Code	Meaning	Your next move
`400`	`VALIDATION`	Invalid or missing field	Fix the request. Check message, date, and format.
`401`	None	Missing, malformed, or expired key	Re-copy or regenerate the Bearer key.
`403`	`INSUFFICIENT_SCOPE` `NO_CALLER`	Scope or caller problem	Drop target, use a Mind Twin Teams key, or verify the key owner.
`404`	`NOT_FOUND`	No first transcript or reachable target	Upload the first transcript for `no twin yet`; otherwise check the teammate and workspace.
`413`	`CONTENT_TOO_LARGE`	Message or transcript too large	Keep MCP at or below 10 MB and REST at or below 50 MB.
`429`	None	Rate limit reached	Wait for `retryAfter`, then retry with backoff.
`500 / 502 / 504`	`INTERNAL` `TIMEOUT`	Transient service or upstream failure	Retry with bounded exponential backoff.

Fast diagnosis

The client sees no tools.

Run the copied install command again, confirm the Bearer key is present, then restart the MCP client.

Status is building with little visible progress.

That is expected for a fresh Mind Twin. In MCP, a blank or zero learned-transcript count is not a live meter. Check periodically. Only failed needs attention.

Status says no twin yet.

This is expected before the first upload. REST returns 404. Upload a transcript to start building.

Status says ready and ingesting.

Keep chatting. The Mind Twin remains ready while the new transcript lands; recall of it sharpens shortly.

The transcript date is unknown.

Ask for the real meeting date. Never guess or default to today. Confirm each transcript separately.

The API says the transcript already exists.

The same content and date were de-duplicated successfully. Do not upload it again.

The key format is rejected.

A valid provisioned key starts with dev_ and contains 41 characters. Re-copy it from MCP Twin.

One key. One workspace.

Your first answer is one request away.

Open MCP Twin, copy the key that is already waiting, and choose the path your software needs.

Open the app Request access