Gateway

@recordist/gateway

MCP server + A2A agent for Recordist (https://recordist.app), the app that writes notes from your calls on-device, with no bot in the call. It lets Claude Desktop, Claude Code, Cursor and other agents read and act on the meetings you recorded, where they are kept.

Get the free Recordist app for Mac, Windows and Linux: https://recordist.app/download?from=npm

• Reads (list, get, transcript, search, action items) work whether or not the Recordist app is running: the gateway talks to the app's local API when it is up and falls back to opening recordist.db read-only when it is not.
• Actions (start and stop recording, add a marker, regenerate notes) need the app. When it is not running they fail with Recordist app is not running.
• Recording asks first. start_recording starts at once only when Allow agents to start recordings is on in Recordist's Settings, then Integrations (off by default). Otherwise Recordist shows its own record card on screen, as it does for the Chrome extension and Stream Deck, and nothing records until the person answers it. Recordist 1.0.4 and earlier show that card only while the Chrome extension switch is on in Settings, then Detection; with both off, the agent is told the recording did not start and the person can start it in Recordist. stop_recording and regenerate_notes are marked destructive, so assistants that honour MCP's hints ask each time.
• Where your meetings go. The gateway itself talks only to the Recordist app on 127.0.0.1 and listens on loopback by default. What it returns goes to the AI assistant you connect, which may send it to its own cloud model. regenerate_notes has the app write notes with the provider set in Recordist's Settings → AI notes, which may also be a cloud service.

Install

npx -y @recordist/gateway --doctor     # check data dir, DB, token, app

Requires Node 20+. better-sqlite3 ships prebuilt binaries for common platforms.

Connect an assistant

Claude Desktop: the extension

The Recordist extension installs in Claude Desktop in one step and needs no configuration. Double-click recordist- .mcpb (build it as in Claude Desktop Extension), or in Claude Desktop open Settings → Extensions → Advanced settings → Install Extension… and choose the file. Claude shows what the extension can do before you install it.

Claude Desktop: by hand

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{

"mcpServers": { "recordist": { "command": "npx", "args": ["-y", "@recordist/gateway"] } } }

Claude Code

claude mcp add recordist -- npx -y @recordist/gateway

or, for the HTTP transport while npx -y @recordist/gateway --http is running (it needs the app's API token, see Authentication):

TOKEN="$(cat ~/Library/Application\ Support/app.recordist.desktop/api_token)"

claude mcp add --transport http recordist http://127.0.0.1:47322/mcp \ --header "Authorization: Bearer $TOKEN"

Claude Code plugin

This repository is also a Claude Code plugin marketplace. The plugin in plugins/recordist starts this gateway, pinned to a published version, and adds a skill for answering from the record:

/plugin install recordist --marketplace recordist-app/gateway

On Claude Code before 2.1.275, add the marketplace first: /plugin marketplace add recordist-app/gateway, then /plugin install recordist@recordist.

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

"mcpServers": { "recordist": { "command": "npx", "args": ["-y", "@recordist/gateway"] } } }

Any Streamable HTTP client

npx -y @recordist/gateway --http          # http://127.0.0.1:47322/mcp

Send Authorization: Bearer with every request.

Authentication

The HTTP transport (--http) and the A2A agent (--a2a) answer only requests that carry Authorization: Bearer , where the token is the contents of /api_token (or RECORDIST_API_TOKEN), the same token the gateway uses for the app's local API. A missing or wrong token gets 401 with WWW-Authenticate: Bearer and nothing else. The one exception is the A2A Agent Card, which stays public so clients can discover the scheme; it lists skills only, never meetings. Neither mode starts when no token is available, and neither does --all, stdio included: open Recordist once so it writes api_token, or run with no flags for stdio alone. The stdio transport needs no token, since only the assistant that launched it can talk to it. --doctor says whether --http and --a2a will require the token or refuse to start.

What the assistant gets

Tools

Resources: recordist://meeting/{id} (JSON) and recordist://meeting/{id}/transcript (Markdown). The resource list shows the 50 most recent meetings.

Prompts: summarize_meeting, draft_followup_email, weekly_review.

A2A agent

npx -y @recordist/gateway --a2a           # http://127.0.0.1:47323/

Agent Card at http://127.0.0.1:47323/.well-known/agent.json (public, no token; authentication.schemes is ["bearer"]); skills mirror the tools above. JSON-RPC 2.0 at / with tasks/send, tasks/get, tasks/cancel and tasks/sendSubscribe (SSE); every JSON-RPC request needs Authorization: Bearer .

Natural-language tasks are routed to a skill with a small keyword router; every completed task returns a text part and a data part with the structured result. To skip the router, send a data part {"skill": "...", "args": {...}}.

TOKEN="$(cat ~/Library/Application\ Support/app.recordist.desktop/api_token)"

curl -s http://127.0.0.1:47323/ \ -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "id": "task-1", "message": { "role": "user", "parts": [ { "type": "text", "text": "What are my open action items from this week?" } ]} } }' | jq .result.artifacts[0].parts

explicit skill call

curl -s http://127.0.0.1:47323/ -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{ "jsonrpc":"2.0","id":2,"method":"tasks/send", "params":{"message":{"role":"user","parts":[ {"type":"data","data":{"skill":"get_transcript","args":{"meeting_id":"01J…","format":"srt"}}} ]}}}'

streaming

curl -N http://127.0.0.1:47323/ -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{ "jsonrpc":"2.0","id":3,"method":"tasks/sendSubscribe", "params":{"message":{"role":"user","parts":[{"type":"text","text":"list my meetings from today"}]}}}'

CLI

npx -y @recordist/gateway                 MCP over stdio (default)

npx -y @recordist/gateway --http MCP over Streamable HTTP on 127.0.0.1:47322/mcp (bearer token) npx -y @recordist/gateway --a2a A2A agent on 127.0.0.1:47323 (bearer token) npx -y @recordist/gateway --all stdio + --http + --a2a (exits if there is no token) npx -y @recordist/gateway --doctor diagnostics: data dir, DB, token, app reachability, HTTP/A2A auth npx -y @recordist/gateway --version --http-port --a2a-port --host

Always run it with npx by its scoped name, @recordist/gateway. A global install (npm i -g @recordist/gateway) puts the same command on your path as recordist-gateway.

--host binds --http and --a2a to another address and exists for containers. Do not expose it on a network interface: the token would cross the network in plain HTTP.

Logs go to stderr; stdout is reserved for the stdio MCP transport.

Environment variables

| RECORDIST_DATA_DIR | macOS ~/Library/Application Support/app.recordist.desktop Windows %LOCALAPPDATA%\app.recordist.desktop Linux ~/.local/share/app.recordist.desktop | Where recordist.db and api_token live | | RECORDIST_API_URL | http://127.0.0.1:47321 | Local API base URL | | RECORDIST_API_TOKEN | contents of /api_token | Bearer token for the local API, and the token --http and --a2a require from callers |

How backend selection works

On each call the gateway probes GET /v1/health (800 ms timeout, result cached for 5 s). If the app answers, the call goes to the API. Otherwise reads open /recordist.db read-only (the app's WAL is never written to) and actions return Recordist app is not running. The database is opened with better-sqlite3 when its native binary matches the Node that runs the gateway, and with node:sqlite (Node 22.13 and later) when it does not. If neither can open it, the error says why for each. FTS5 (segments_fts) is used for search when present, with a LIKE fallback otherwise.

Security notes

• The gateway binds 127.0.0.1 by default. --host exists for containers; do not expose it on a network interface. The Streamable HTTP transport enables DNS-rebinding protection and only accepts its own Host (127.0.0.1 or localhost by default). The A2A agent accepts only its own Host, no browser Origin unless allow-listed, and JSON-RPC POSTs only as application/json.
• The gateway itself talks only to the Recordist app on 127.0.0.1. What it returns goes to the AI assistant you connect, which may send it to its own cloud model, so connect only an assistant you trust with your meetings.
• --http and --a2a require Authorization: Bearer on every request (the A2A Agent Card excepted), compared in constant time, so other user accounts on the machine cannot read meetings through them. Programs running under your own account can read api_token, so the token does not separate them from you.
• The API token is read from /api_token, which the app writes with mode 0600. --doctor warns if the file is group/world readable. Never commit or share it; anyone with the token can control recording on that mac