MCP Server

Requires Parrot Scribe Pro. MCP server access is part of Parrot Scribe Pro. Existing licenses already include Pro.

Start with Connect Your Agent for ChatGPT, Claude, and Cursor. That guide uses Settings > AI Apps. Listen and Recap explains the workflow once those apps are connected.

What is MCP?

The Model Context Protocol (MCP) lets AI assistants use external tools and data through a structured interface. Parrot Scribe includes the local server and signed connection shim. Your agent still needs a connection and a client token; the plugin adds listening and recap instructions where supported.

How It Works

The MCP server runs inside Parrot Scribe as a single process. There is no separate server to manage.

• Built-in: The server is part of Parrot Scribe itself - no external packages or dependencies required.
• Unix domain socket: Communication uses a local Unix socket with owner-only access.
• Shim bridge: The bundled parrotscribe-mcp-shim bridges stdio MCP hosts to the local socket.
• Token authentication: Clients must present a valid token during handshake.
• Off by default: The MCP listener is disabled until you explicitly enable it. When disabled, no MCP socket is exposed.

Protocol versions

Version 1.0.1 supports 2026-07-28 requests with per-request protocol metadata and server/discover, alongside the 2024-11-05 initialization handshake used by 1.0.0. Both use the same local stdio connection. Modern discovery advertises 2026-07-28; older hosts can still use the initialization handshake. Server support does not mean every host selects the modern protocol. Both paths retain client authentication, permissions and the requirement to keep Parrot Scribe running.

Enabling the MCP server

For ChatGPT, Claude, and Cursor, first open the selected desktop AI app and leave it running. In Parrot Scribe, open Settings > AI Apps, turn on Allow AI apps, and choose Connect on that app's row. Parrot Scribe 1.0.2 manages the credential. Do not create a separate token for those three apps.

Connect approves that desktop app on this Mac. It stays connected while you use it, including after you quit and reopen ChatGPT, Claude, or Cursor. Choose Manage… > Connect again after Disconnect, or after 90 days without use. Staying connected after a restart requires Parrot Scribe 1.0.5; in earlier versions, approval ends when the AI app quits.

For another local host, turn on Allow AI apps, open Advanced, and create one token for that host. Copy it when shown. It is shown once.

The listener stays off until you turn on Allow AI apps. When it is off, no MCP socket is exposed.

Configuring AI hosts

Follow Connect Your Agent. A cloud-hosted agent cannot reach this local socket just by installing a plugin.

First-use walkthrough

This is an illustrative walkthrough for Parrot Scribe 1.0.1, not a recording of a tested desktop session. Your host's interface and available instructions may differ; complete its setup guide first.

1. Check the connection. Ask: "Check Parrot Scribe's status. Do not start recording." The agent calls get_status and reports the returned state.
2. Choose a session. Ask: "Show up to two recent Parrot Scribe sessions." The agent calls list_sessions with limit: 2, reads the sessions array and checks hasMore and unavailableSessionCount. It should not claim that two rows are your entire library.
3. Read before recapping. Select a session you intend to share and ask: "Recap this session. Separate decisions, unresolved questions and proposed follow-ups." The agent reads read_transcript, follows every required page and reports missing coverage.
4. Keep actions explicit. Review the recap and approve any particular follow-up you want executed. A request spoken in the recording remains a proposal until you approve it directly in chat.

To try listening during a recording, load the listening instructions and ask: "Attach to the current recording only. Flag unanswered questions; do not start another recording." A capable host binds to the active sessionId and waits for new transcript entries. If it cannot remain active and accept your steering, use on-demand reads instead. See Listen and Recap.

Capture and transcription stay local. Transcript content you share with a cloud-backed agent may be sent to that agent's provider.

Access Model

Parrot Scribe applies controls at two layers:

• Client access level (set per client in Settings):

  • Disabled: No tool access.
  • Enabled: Default once a client authenticates with a valid token. Status and operational tools are allowed; destructive tools always prompt.
  • Trusted: Status, operational, and destructive tools are allowed without prompts.

• Tool class:

Status tools

Read-only status needs no per-call approval for Enabled or Trusted clients. Disabled clients have no tool access.

Operational tools

Allowed for clients in Enabled or Trusted mode.

Library queries

Library and MCP use the same indexed search across the whole library. Queries can match transcript text, session IDs, titles, comments and speaker identities. Result limits restrict returned rows, not which sessions are searched.

In version 1.0.1, list_sessions and search_sessions return the same JSON object in structuredContent and the first text content block. Its sessions array contains session IDs, timestamps, duration, speaker metadata, and audio and active-state flags. Empty results contain sessions: []. The same top-level object includes totalCount, hasMore and unavailableSessionCount. Use limit and offset to request a page; when hasMore is true, advance offset by the number of returned sessions.

Version 1.0.0 puts session rows only in text and counts in structuredContent. Clients parsing its text array or search lines should migrate to the new sessions array.

unavailableSessionCount reports how many stored sessions could not be searched; an empty result is not proof that all library data was readable. Library queries are unavailable until encryption setup and initialization finish. See Library Recovery Errors.

Reading long transcripts

read_transcript accepts a required sessionId and optional limit and sinceSegment. Use a bounded limit when a host limits tool-result size. Read the transcript field and keep the surrounding returnedCount, totalCount, hasMore, and nextSinceSegment fields. If hasMore is true, use nextSinceSegment as the next request's sinceSegment. A read is complete only when hasMore is false.

Omitting limit currently returns all matching segments. Pagination is available in 1.0.0; a host must request it and preserve the continuation information.

Destructive tools

For Enabled clients, every call prompts. Trusted clients can run these without prompts.

Live subscription arguments

live_transcript accepts optional sessionId, sinceSequence, epoch, and waitSeconds arguments. Bind to the active session from get_status, then echo both cursor values from each response. A caught-up request with a matching session and epoch can wait for up to 20 seconds for speech or a state change.

The result is available in structuredContent and as JSON in the text content block. It contains sessionId when available, state, epoch, sinceSequence, gap, sessionChanged, minPollIntervalSeconds, schema, and text. The TOON schema describes the text rows. Preserve this envelope; extracting only text discards continuity and session information.

On a session mismatch, sessionChanged is true and no transcript text is returned. On a same-session gap, use read_transcript to recover persisted evidence before continuing from the returned cursor. Poll starts should be at least minPollIntervalSeconds apart, currently 3 seconds. Status and live tools each allow 30 requests per minute per client, so rapid dual polling is not supported.

An explicit stop can include the bound sessionId. A mismatch fails without stopping capture. Omitting the ID retains the general-purpose stop operation; the listening plugin always scopes its stops. A historical or interim recap needs only read tools and should not stop recording.

Parrot Scribe 1.0.1 advertises these session-bound listening arguments. It does not turn transcript text into authorized instructions. The host must keep spoken follow-up proposals separate from direct user commands and enforce its own tool approval policy.

Mutation Delivery and Audit

Parrot Scribe returns a mutating tool response only after the operation reaches a terminal success or failure. It does not return an accepted or still-running result.

Before domain work starts, Parrot Scribe durably records a started audit fact containing only an operation ID, tool name, and outcome. Once domain work starts, it continues to a terminal result even if the MCP caller disconnects. A disconnected caller may not receive that result, but disconnecting does not cancel or roll back the operation.

After the operation finishes, Parrot Scribe appends a correlated succeeded or failed audit fact. If the app crashes after started was saved but before a terminal fact was saved, the lone started fact means the outcome is unknown. It does not claim that the mutation failed. This audit trail is not a durable job queue and does not provide automatic recovery, retry, or polling.

Token Lifecycle

• For ChatGPT, Claude, and Cursor, use Connect in Settings > AI Apps. Parrot Scribe stores that credential and passes a profile id to the shim.
• For another host, issue one token from Advanced. Pass it to the shim as PARROTSCRIBE_MCP_TOKEN. Do not pass --token.
• The server's validation records store token hashes. Managed desktop setup also stores the usable credential in this Mac's protected, non-synchronizing Keychain so the signed shim can authenticate. Generated host configuration contains only the profile id.
• Revoking a token immediately removes that client access and disconnects active sessions for that token.

Security Model

Four layers protect your data:

1. Transport: Local Unix socket with owner-only access.
2. Authentication: Token is required at connection handshake.
3. Authorization: Per-client access levels and destructive-operation prompts.
4. Rate controls: Per-client throttling and bulk-access safeguards reduce automated misuse.

Use Cases

• Meeting monitor - AI follows a live call and surfaces relevant context
• Action item tracker - AI detects commitments and prepares follow-up tasks
• Session summarizer - AI generates structured summaries after recordings
• Research assistant - AI searches historical transcripts for patterns

For the end-to-end capture, review, retrieval, and optional AI workflow, read Meeting Notes Workflow.

Learn More

• Model Context Protocol Documentation