Mindstamp MCP and Agent Compatibility

Connect an AI agent to your Mindstamp account to create interactive videos,
edit interactions, preview drafts, create personalized links, and read reports.
The agent uses your Mindstamp permissions.

The expanded tools on this page require MCP server version 0.2.0. At the
release check on September 8, 2026, the public server still reported 0.1.0.
Check the server card
and your connection's tools/list before using a new tool. Reconnect after
the server update if a tool is missing. A docs update does not update the server.

• Endpoint: https://app.mindstamp.com/mcp (Streamable HTTP, JSON-RPC 2.0).
• Authentication: OAuth authorization code with PKCE and discovery, or an
  existing Mindstamp API token as a bearer token.
• Availability: reads need an active account and AI consent; writes need the
  account's API-plan access. get_capabilities reports the current access.
• AI features are off until an account owner turns them on at
  https://app.mindstamp.com/ai-settings. The same page lists every connected
  agent and lets the owner revoke access.

Connect

Remote MCP clients

Add this endpoint as a remote Streamable HTTP server and choose OAuth.
Client and workspace settings determine whether you can add a custom server.

https://app.mindstamp.com/mcp

The client discovers the authorization server from
https://app.mindstamp.com/.well-known/oauth-protected-resource, registers
itself at /oauth/register, and runs the standard code + PKCE flow. Access
tokens expire; clients can use refresh tokens to keep the connection active.

Claude Code (CLI)

claude mcp add --transport http mindstamp https://app.mindstamp.com/mcp

Open /mcp and complete OAuth login.

Codex

codex mcp add mindstamp --url https://app.mindstamp.com/mcp
codex mcp login mindstamp
codex mcp list

Complete the Mindstamp sign-in and consent steps. Start a new Codex session
after setup so it can load the tools. See the
official Codex MCP guide
for client settings.

With an existing API token

Send your Mindstamp API token as a bearer token:

Authorization: Bearer <your-api-token>

Create tokens in your Mindstamp account if your plan includes API access.
Keep tokens in the client's credential settings. Do not put them in prompts,
spreadsheets, shared scripts, or source control.

Scopes

An existing API token (scope public) has full access, matching the REST API.
Personalized-link creation and updates need both write and read:viewers.
Raw report tools require read:viewers; query_report does not return a
redacted export without that scope. Aggregate tools can work with read,
but viewer-identity and variable filters need read:viewers.

The server maps OAuth write to internal write:settings and
write:interactions scopes. These names can appear in get_capabilities.
Account and record permissions still apply to all tokens.

Token lifetime

OAuth access tokens expire after one hour. Clients can refresh them and receive
a new token pair. Using the new access token revokes the previous refresh
token. Regular Mindstamp API tokens have no expiry, but you can revoke them.

Tools

Call get_capabilities to check tools, scopes, and account access. tools/list
returns typed input schemas, safety annotations, and an output envelope schema.

Version 0.2.0 contains 49 tools, including 28 new tools. The new tools are
get_capabilities and those in this table:

Read: list_videos, get_video, get_transcript, get_video_stats,
get_question_results, list_views, get_view, list_interactions.

Build and edit: add_button, add_questions, add_text, add_hotspot,
set_chapters, delete_interaction.

Settings: update_video_settings, set_end_screen_link,
set_end_screen_branch, configure_lead_capture.

Account and high-impact: apply_brand_design, set_publish_state,
delete_video (each requires confirm: true).

Call tools/list for the current set and each tool's input schema.
Most video tools need the video's UUID in video_id. Use list_videos to
find it. A watch URL token is not the same as the video's UUID.

Personalized links from a spreadsheet

An agent with file access, such as Codex, can read an XLSX or CSV file, create
links through Mindstamp MCP, and write the returned URLs into a new file.
Mindstamp accepts recipient records. The agent reads and writes the
spreadsheet; MCP does not accept the spreadsheet file itself.

Example prompt:

Use Mindstamp video ID <video-uuid> and the attached spreadsheet. Create
one personalized link for each recipient row. Map Name, Email, Phone, and
Customer ID to the recipient fields, and Company to the COMPANY variable.
Keep the original columns and row order. Add Mindstamp Link ID and
Personalized URL columns, then return a new spreadsheet. Do not send
messages or change the video's publication state. Keep the request keys
so a retry does not create duplicate links.

The agent must map your file's actual columns. Keep phone numbers and customer
IDs as strings to preserve leading zeros. Omit empty optional identity fields.
A recipient must contain some data beyond the active flag.

Custom variable values can be strings, numbers, booleans, or null. The server
converts variable keys to uppercase. Keep keys distinct after that conversion.
Use {{COMPANY}}, for example, in video text that should use the recipient's
company value. Creating a link does not add that text to the video.

Use top-level identity fields for name, email, phone, and customer ID.
Do not put NAME, EMAIL, PHONE, CUSTOM_ID, PLINK_ID, PKEY,
PREVIEW_TOKEN, or TEST_PLAYBACK_TOKEN in variables.

Call create_personalized_links with a recipient array and a request key:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_personalized_links",
    "arguments": {
      "video_id": "<video-uuid>",
      "idempotency_key": "<unique-key-for-this-recipient-batch>",
      "recipients": [
        {
          "name": "Alex Rivera",
          "email": "[email protected]",
          "custom_id": "000123",
          "variables": { "COMPANY": "Example Company" }
        },
        {
          "name": "Sam Lee",
          "email": "[email protected]",
          "custom_id": "000124",
          "variables": { "COMPANY": "Example Studio" }
        }
      ]
    }
  }
}

The result contains links, count, published, and messages_sent.
Each entry in links contains id, url, and active, in the same order
as recipients. MCP structuredContent also includes action_id and replayed.

Check the returned count, then copy each link ID and URL to its spreadsheet
row. Keep a row-to-request map if the agent uses more than one call. The
response does not echo spreadsheet row numbers or recipient identities.

• A successful call creates all recipients in that call. An invalid recipient
  causes all database changes for that call to roll back. The tool does not return partial
  successes for individual rows.
• After a lost response, retry with the same idempotency_key and arguments.
  The server returns the saved result. Use a new key if you change the arguments.
• A new job with a new key can create another link for the same person.
  The tool does not deduplicate requests by email or custom_id.
• messages_sent is false. This tool does not email or text recipients.
• Link creation does not publish the video. Check published before sending
  links. The video's access settings still apply.

Use list_personalized_links to read existing links, recipient fields, URLs,
and stored statistics. Follow next_cursor until it is null.
Use update_personalized_link with video_id, link_id, and changes
to edit a link or disable it with active: false.

An update's variables field replaces the whole variable map. Read the current
values before changing them. These link write tools do not support setting
expiry, personal intro clips, or playlist targets in this release.

File to interactive video

1. Call create_video with title, filename, and idempotency_key. It creates
   an unpublished video. You can instead use an existing source_id or a
   public MP4/HLS source_url; choose exactly one of these three inputs.
2. After user approval for the file transfer, call prepare_video_upload with
   video_id, confirm: true, and idempotency_key. Use its returned endpoint
   and short-lived headers with a TUS 1.0 client to upload the local file.
   Do not send local paths or file bytes to MCP. Keep the upload ticket private.
3. Check get_video_status until authoring_ready is true. Add interactions
   with create_annotation and use get_video_preview to inspect the draft.
4. Create recipient links without sending messages. Publish with
   set_publish_state only after user approval. Get the public link and embed
   code with get_share_links.

An agent needs a local upload client to transfer the bytes and a browser to
inspect the preview. Creating an upload ticket does not upload the file, and
returning a preview URL does not prove that playback works.

update_annotation needs expected_revision from a previous read. It preserves
the annotation ID. apply_video_edits rolls back all child database edits on a
failure. It excludes uploads and publication. Supported changes can be reversed
with undo_action; not all writes support undo.

Use the same idempotency_key and arguments after a lost write response. A replay
returns the original action ID. Use a new key for a different action. Remote
upload-slot creation can have an unknown result after a connection failure;
inspect that slot before retrying.

Complete reports

Call get_report_schema, then query_report for the dataset and fields you need.
Continue with next_cursor until it is null. Keep the dataset, filters, fields,
and format unchanged across pages. CSV output is available with format: "csv";
use format: "json" for raw values.
There is no total-row cutoff. One response contains one page. For the next page,
set cursor to the returned next_cursor. Keep one header when joining CSV
pages; each response contains its own csv text and JSON rows.

Authored interactions are annotations. Read them with list_annotations or
get_annotation. The interactions report contains viewer events.

Example query_report arguments:

{
  "dataset": "views",
  "filters": {
    "video_id": "<video-uuid>",
    "started": "2026-09-01",
    "finished": "2026-09-07"
  },
  "fields": ["id", "viewer_email", "percentage", "correctness", "streamed_seconds"],
  "format": "csv"
}

Date filters use UTC and select views by their start time. started is
inclusive; a date-only finished includes the end of that UTC date. For linked
datasets, view filters select records associated with those views, not records
by the recipient or event creation date. Without view filters, interaction
reports can include events that have no finalized view.

is_complete means the session was finalized. For a watched-percentage
threshold, use min_percentage. streamed_seconds measures media streamed;
duration is media length.

get_insights uses the app's calculations on all matching views. Its view_time
and engagement_time values use minutes. graph_report returns SVG, a Vega-Lite
specification, and chart values; it does not send data to a chart service.
get_video_retention uses the app's retention calculation. Cached retention in
get_insights appears under all_time_cached_retention and is all-time even
when other insight filters apply.

The raw report datasets cover views, interaction events, question responses,
viewers linked to matching views, and video personalized links. They do not
expose passwords, API tokens, or integration secrets. They are not an export of
every internal table.

Graph reporting data

Example graph_report arguments:

{
  "metric": "views",
  "dimension": "day",
  "kind": "line",
  "filters": {
    "video_id": "<video-uuid>",
    "started": "2026-09-01",
    "finished": "2026-09-07"
  }
}

Metrics include views, viewers, interactions, watch_seconds,
engagement_seconds, average_percentage, average_correctness,
correct_answers, and incorrect_answers. Group by day, week, month,
video, country, language, or device. Chart kinds are bar and line.

The server calculates chart values across all matching views. Time groups use
UTC. The result contains svg, vega_lite, and the plotted data. An agent
can save the SVG or use the values in a spreadsheet or another chart tool.

Example

// tools/call: add a knowledge check at 45 seconds
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_questions",
    "arguments": {
      "video_id": "<uuid>",
      "questions": [{
        "prompt": "Which fire class involves flammable liquids?",
        "answers": ["Class A", "Class B", "Class C", "Class K"],
        "correct_answer": "Class B",
        "time": 45
      }]
    }
  }
}

Quick test with curl

Use a Mindstamp OAuth or API bearer token. tools/list needs no
consent, but requires a valid token. tools/call, including get_capabilities,
needs AI features turned on for the account.

curl --fail-with-body --silent --show-error https://app.mindstamp.com/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A missing or revoked token returns 401 with a WWW-Authenticate header that
points to the protected resource metadata, which is how OAuth clients discover
the authorization server.

After a server update, reconnect or restart the client to load the current
tools. Sign in again if the existing token lacks the required scopes.

Errors

Tool failures come back as a normal tools/call result with isError: true.
Check this flag even if the HTTP request succeeded.
The text ends with (code: <code>):

Protocol-level problems (bad JSON, unknown method) use JSON-RPC error
objects with the standard codes.

Safety

• Every action is authorized as the connecting user, within their permissions.
• Tool results include an action_id in structuredContent. Save it with the request and result.
• Use undo_action for supported changes; check get_capabilities before promising undo.
• Tier-3 tools require confirm: true after human approval. These include upload preparation, access changes, publishing, account branding, and video deletion.
• Product data (transcripts, titles, viewer answers) is treated as data, never
  as instructions to the agent.

Signed preview URLs expire. Test playback excludes Mindstamp report views and
response events. External links and client-side integrations can still run.
Preview in a muted browser and inspect the result before publishing.

Current limits

The tool list defines MCP support. Version 0.2.0 does not cover every action
in the Mindstamp UI. It does not expose video duplication or media replacement,
playlist or folder management, caption removal, local non-video asset uploads,
dubbing, certificate setup or issuance, integration setup, account
administration, or billing.

The connected agent needs its own file tools to read and return spreadsheets.
Personalized-link write tools support the fields listed above; other fields
visible in a report do not imply write support.

Discovery documents

• https://docs.mindstamp.com/reference/mcp-agents (this page)
• https://app.mindstamp.com/.well-known/oauth-protected-resource
• https://app.mindstamp.com/.well-known/oauth-authorization-server
• https://app.mindstamp.com/.well-known/mcp/server-card.json
• https://app.mindstamp.com/auth.md