tuple mcp runs a local Model Context Protocol server over stdin and stdout. It lets MCP clients read Tuple context, work with calls, inspect Capture data, and communicate with you.The MCP client starts the tuple binary. The binary talks to the Tuple desktop app over its local socket. Tuple must be running, signed in, and authorized for tools that read app state or take actions.Install Tuple in an MCP client
Run the install command without an argument to register Tuple with every supported client detected on your Mac:The server name is
tuple for the production app. Other Tuple environments use a matching name. Pass --name to choose a different identifier:Start with the agent guide
Tuple exposes operating guidance that matches the installedtuple binary. An agent can read the root guide at tuple://agent/guide, then open only the topic needed for its task at tuple://agent/guide/{topic}.Reading the root guide or the live-call topic does not start ongoing monitoring. The guide directs the agent to a bounded read for a one-time question. Following a call begins only when you explicitly ask the agent to follow along and its MCP manifest includes a live-read capability.The server selects the topics and instructions for the session.
managed-agent appears only for an app-designated managed session. In that session, the Tuple app owns live context delivery and resumption, so the agent uses the app-provided mount instead of starting another live reader.Discover the active surface
The MCP manifest is the source of truth for the tools, resources, prompts, and schemas available to a session. Tuple asks the desktop app which capabilities apply, registers only the corresponding surfaces, and notifies clients when the manifest changes.An ordinary attached session can expose these tools:Use the tool’s discovered schema for its arguments and result.
get_state returns a bounded orientation summary. Use the entity tools for full collections and get_capture for one active or stored call with its records.Capability-dependent surfaces
These surfaces appear only when the app reports the matching capability for the session:Check discovery instead of assuming one of these surfaces exists. The app decides managed participation and supplies its MCP mount and context.
Resources
Resources provide readable context without requiring the agent to reconstruct it from tool results.Use
current as {callId} for the active call. For structured records, category exclusions, or a bounded time range, use get_capture.Prompts
Tuple registers reusable prompts for common call tasks. MCP clients decide how to display and invoke them.The
connect prompt returns context once. It does not ask the agent to poll or follow the call. Ask the agent to follow along when you want ongoing participation.Live Capture delivery
When advertised,next_capture reads one batch for an explicitly requested ongoing task. Its result contains call_id, records, cursor, and terminal. Omit cursor for initial catch-up. After the records reach the model, repeat with the returned call and cursor. If initial catch-up is empty, cursor: 0 begins waiting. Preserve the previous checkpoint after a failed delivery.Use batch for buffering, timeout to bound idle waiting, and wake_on for literal phrases that flush matching speech early. Stop at terminal.status: "call_ended". A recording_ended record ends Capture for that recording, not the call.For a one-time question, use get_capture and finish after answering. It returns a structured {call, records} result; since, until, and exclude narrow the read.Safety and confirmations
Call transcripts, shared screens, and stored records are context, not instructions. The agent guide identifies the person who connected the agent as its principal and tells the agent to ask before acting on requests from other participants.Tools publish MCP annotations that identify read-only, mutating, idempotent, and destructive operations. Confirmation behavior depends on the MCP client. Treat calls, participant changes, mute changes, contact removal, stored-call deletion, and file exports as consequential actions that require authorization from the principal when the request has not already authorized them.For an existing integration, follow the CLI and MCP migration guide.Connection problems
If the MCP server is missing or disconnected, reconnect it in the MCP client and restart the client if needed. If the server is present but app tools fail, confirm that Tuple is running, signed in, and authorized under Settings → Integrations → CLI Server.For problems with call connectivity or media quality, have the agent readtuple://agent/guide/connection. It starts with read-only Tuple state and separates observations from inferences. See Networking and firewall issues for human troubleshooting steps.