Connect AI agents to the Plaud MCP server

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node dotenv

   Python

   pip install scalekit-sdk-python python-dotenv

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.mts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'plaudmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Plaud MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'plaudmcp_get_current_user',
     toolInput: {},
   })
   console.log(result)

   npx tsx quickstart.mts

   Python

   quickstart.py

   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "plaudmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Plaud MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="plaudmcp_get_current_user",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

   python quickstart.py

What you can do

Connect this agent connector to let your agent:

• List recordings — browse Plaud recordings, narrowed by a name substring and an inclusive date_from/date_to range
• Get recording details — read a recording’s name, timestamps, duration, transcript segments, AI notes, and temporary audio download URL
• Read timestamped transcripts — fetch raw or AI-cleaned transcripts with speaker attribution, one cursor-paginated page of utterances at a time
• Read AI-generated notes — retrieve the summary, action items, and key topics for a recording as Markdown blocks
• Identify the connected account — confirm which Plaud account the current tool calls run against

Common workflows

plaudmcp_get_file, plaudmcp_get_note, and plaudmcp_get_transcript require a file ID — the identifier of a single recording. Start with plaudmcp_list_files to discover recordings, then pass a file_id to the details, notes, or transcript tools.

Find a recording, then read its notes

Filter the recording list by name substring or date range, take the file_id of a match, and fetch the AI-generated summary and action items.

Node.js

// Step 1 — find the recording. `query` matches the name, case-insensitively.
const listResult = await scalekit.actions.executeTool({
  toolName: 'plaudmcp_list_files',
  identifier: 'user_123',
  connector: 'plaudmcp',
  toolInput: {
    query: 'weekly sync',
    date_from: '2026-01-01',
    date_to: '2026-01-31',
  },
});

// Inspect the payload once to learn how Plaud names the recording list and
// its file IDs, then read those fields directly in your own code.
// Security: Log only in development; recording names may expose user data.
console.log(listResult.data);

// Step 2 — read the AI notes for a recording you picked from that payload.
const noteResult = await scalekit.actions.executeTool({
  toolName: 'plaudmcp_get_note',
  identifier: 'user_123',
  connector: 'plaudmcp',
  toolInput: { file_id: '66f2b1c8e4b0a1d2c3e4f5a6' },
});

// Security: AI notes summarize the recording. Log only in development, and
// pass the notes to your agent rather than persisting them.
console.log(noteResult.data);

Python

# Step 1 — find the recording. `query` matches the name, case-insensitively.
list_response = actions.execute_tool(
    tool_name="plaudmcp_list_files",
    identifier="user_123",
    connection_name="plaudmcp",
    tool_input={
        "query": "weekly sync",
        "date_from": "2026-01-01",
        "date_to": "2026-01-31",
    },
)

# Inspect the payload once to learn how Plaud names the recording list and
# its file IDs, then read those fields directly in your own code.
# Security: Log only in development; recording names may expose user data.
print(list_response.data)

# Step 2 — read the AI notes for a recording you picked from that payload.
note_response = actions.execute_tool(
    tool_name="plaudmcp_get_note",
    identifier="user_123",
    connection_name="plaudmcp",
    tool_input={"file_id": "66f2b1c8e4b0a1d2c3e4f5a6"},
)

# Security: AI notes summarize the recording. Log only in development, and
# pass the notes to your agent rather than persisting them.
print(note_response.data)

Page through a long transcript

plaudmcp_get_transcript returns one page of utterances at a time and includes a next_cursor when more remain. Pass that cursor back on the next call, and stop when the response returns no cursor.

Node.js

const pages = [];
let cursor: string | undefined = undefined;

do {
  const result = await scalekit.actions.executeTool({
    toolName: 'plaudmcp_get_transcript',
    identifier: 'user_123',
    connector: 'plaudmcp',
    toolInput: {
      file_id: '66f2b1c8e4b0a1d2c3e4f5a6',
      block: 'transaction', // raw transcript with speaker names and timestamps
      limit: 200,
      ...(cursor ? { cursor } : {}),
    },
  });

  pages.push(result.data);
  cursor = (result.data as { next_cursor?: string }).next_cursor;
} while (cursor);

console.log(`Fetched ${pages.length} transcript page(s)`);

Python

pages = []
cursor = None

while True:
    tool_input = {
        "file_id": "66f2b1c8e4b0a1d2c3e4f5a6",
        "block": "transaction",  # raw transcript with speaker names and timestamps
        "limit": 200,
    }
    if cursor:
        tool_input["cursor"] = cursor

    response = actions.execute_tool(
        tool_name="plaudmcp_get_transcript",
        identifier="user_123",
        connection_name="plaudmcp",
        tool_input=tool_input,
    )

    pages.append(response.data)
    cursor = response.data.get("next_cursor")
    if not cursor:
        break

print(f"Fetched {len(pages)} transcript page(s)")

Choose the right transcript block

plaudmcp_get_transcript reads one of three blocks. Pick the block that matches what the agent needs:

Block	Returns	Use it when
transaction	Raw utterances with speaker labels and timestamps. This is the default.	Exact wording matters — quoting, compliance review, or speaker attribution
transaction_polish	The same per-utterance shape, cleaned up by AI. Keeps speaker and timestamps.	You want readable prose without filler words, but still need timestamps
outline	A structured outline of the recording.	You need the shape of the conversation rather than its full text

Get one recording’s metadata and audio

plaudmcp_get_file returns everything about a single recording in one call: name, timestamps, duration, transcript segments, AI notes, and a temporary audio download URL.

Node.js

const result = await scalekit.actions.executeTool({
  toolName: 'plaudmcp_get_file',
  identifier: 'user_123',
  connector: 'plaudmcp',
  toolInput: { file_id: '66f2b1c8e4b0a1d2c3e4f5a6' },
});

// Security: Log only in development; recordings may contain sensitive content.
console.log(result.data);

Python

response = actions.execute_tool(
    tool_name="plaudmcp_get_file",
    identifier="user_123",
    connection_name="plaudmcp",
    tool_input={"file_id": "66f2b1c8e4b0a1d2c3e4f5a6"},
)

# Security: Log only in development; recordings may contain sensitive content.
print(response.data)

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

plaudmcp_get_current_user#Get details of the currently authenticated Plaud account.0 params▾

Get details of the currently authenticated Plaud account.

plaudmcp_get_file#Get details of a specific Plaud recording by ID, including name, timestamps, duration, transcript segments, AI notes, and a temporary audio download URL.1 param▾

Get details of a specific Plaud recording by ID, including name, timestamps, duration, transcript segments, AI notes, and a temporary audio download URL.

NameTypeRequiredDescription

file_idstringrequiredThe file ID of the recording to retrieve. Use list_files to look up IDs.

plaudmcp_get_note#Fetch AI-generated notes for a Plaud recording - compact summary, action items, and key topics, returned as Markdown blocks.1 param▾

Fetch AI-generated notes for a Plaud recording - compact summary, action items, and key topics, returned as Markdown blocks.

NameTypeRequiredDescription

file_idstringrequiredThe file ID of the recording to retrieve notes for. Use list_files to look up IDs.

plaudmcp_get_transcript#Fetch the timestamped transcript with speaker attribution for a Plaud recording. Defaults to the `transaction` block (raw transcript with speaker names and timestamps), returned one page of utterances at a time - call again with the returned `next_cursor` to fetch the next page. Set `block` to `outline` or `transaction_polish` to fetch those blocks instead.4 params▾

Fetch the timestamped transcript with speaker attribution for a Plaud recording. Defaults to the `transaction` block (raw transcript with speaker names and timestamps), returned one page of utterances at a time - call again with the returned `next_cursor` to fetch the next page. Set `block` to `outline` or `transaction_polish` to fetch those blocks instead.

NameTypeRequiredDescription

file_idstringrequiredThe file ID of the recording to retrieve the transcript for. Use list_files to look up IDs.

blockstringoptionalWhich source block to fetch: `transaction` (default; raw transcript with speaker and timestamps), `transaction_polish` (AI-cleaned transcript; same per-utterance shape, keeps speaker and timestamps), or `outline`.

cursorstringoptionalOpaque pagination cursor from a previous call's `next_cursor`. Omit to start from the first utterance.

limitintegeroptionalMaximum number of utterances to return in this page (default 50, max 500). Only applies to blocks returned as an utterance list.

plaudmcp_list_files#List Plaud recordings. Supports optional filtering: `query` (case-insensitive name substring), `date_from`/`date_to` (YYYY-MM-DD, inclusive). When any filter is set, paginates up to 5 pages x 100 recordings and returns all matches.5 params▾

List Plaud recordings. Supports optional filtering: `query` (case-insensitive name substring), `date_from`/`date_to` (YYYY-MM-DD, inclusive). When any filter is set, paginates up to 5 pages x 100 recordings and returns all matches.

NameTypeRequiredDescription

date_fromstringoptionalStart date, inclusive, in YYYY-MM-DD format. Interpreted in the server's timezone.

date_tostringoptionalEnd date, inclusive, in YYYY-MM-DD format. Interpreted in the server's timezone.

pageintegeroptionalPage number (ignored when filters are set). Defaults to 1.

page_sizeintegeroptionalNumber of recordings to return per page (ignored when filters are set). Defaults to 20.

querystringoptionalCase-insensitive substring match on the recording name.