@speakai/mcp-server 1.39.3 → 1.39.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,11 +2,12 @@
2
2
  <img src="assets/logo.png" alt="Speak AI" width="120" />
3
3
  </p>
4
4
 
5
- <h1 align="center">Connect Speak AI to Claude or ChatGPT in 60 seconds</h1>
5
+ <h1 align="center">Connect Speak AI to Claude, ChatGPT and other AI assistants in 60 seconds</h1>
6
6
 
7
7
  <p align="center">
8
8
  <strong>For researchers, revenue teams, meeting-heavy teams, and media workflows.</strong><br/>
9
- No Terminal. No npm. No JSON config files.
9
+ No Terminal. No npm. No JSON config files.<br/>
10
+ Works with Claude, ChatGPT, Cursor, VS Code, Windsurf, Muse, OpenClaw and any MCP client.
10
11
  </p>
11
12
 
12
13
  <p align="center">
@@ -23,26 +24,26 @@
23
24
 
24
25
  ## What this does
25
26
 
26
- Speak AI transcribes your interviews, sales calls, research sessions, webinars, podcasts, and team meetings — then extracts AI insights like summaries, action items, sentiment, and themes.
27
+ Speak AI transcribes your interviews, sales calls, research sessions, webinars, podcasts, and team meetings, then extracts AI insights like summaries, action items, sentiment, and themes.
27
28
 
28
- This connector (built on MCP — the standard way Claude and ChatGPT connect to apps) brings all of that into Claude or ChatGPT. Once installed, you can ask:
29
+ This connector is built on MCP, the open standard AI assistants use to connect to apps, so it brings all of that into Claude, ChatGPT, Cursor, Muse or any other MCP-compatible assistant. Once installed, you can ask:
29
30
 
30
31
  - "Find the last 10 customer interviews that mention pricing, group the feedback by theme, and cite the source recordings."
31
32
  - "Summarize this week's team meetings into decisions, action items, owners, and unresolved risks."
32
33
  - "Pull exact customer quotes about onboarding friction from recent research calls and format them for a product brief."
33
34
  - "Find a strong 30-second highlight from the latest webinar, create a clip, and export captions."
34
35
 
35
- The AI does the searching, summarizing, and citing. Your recordings stay in your Speak AI workspace — Claude and ChatGPT just query them through this connector.
36
+ The AI does the searching, summarizing, and citing. Your recordings stay in your Speak AI workspace; the assistant only queries them through this connector.
36
37
 
37
38
  ---
38
39
 
39
40
  ## Install (pick your tool)
40
41
 
41
- > **Two paths to install** — pick whichever feels easier. The one-click connect path approves access via a permission popup; the manual path pastes an API key into a header.
42
+ > **Two paths to install**: pick whichever feels easier. The one-click connect path approves access via a permission popup; the manual path pastes an API key into a header.
42
43
 
43
- > **Don't know which one to pick?** If you already use Claude or ChatGPT, install for whichever one you have.
44
+ > **Don't know which one to pick?** Install it in the AI assistant you already use. Every option below connects to the same Speak AI workspace.
44
45
 
45
- > Speak AI's connector address (paste this into your AI tool's connector settings — it's the same idea as pasting a Zoom link into your calendar): `https://api.speakai.co/v1/mcp`
46
+ > Speak AI's connector address (paste this into your AI tool's connector settings; it's the same idea as pasting a Zoom link into your calendar): `https://api.speakai.co/v1/mcp`
46
47
 
47
48
  ### Claude.ai (web)
48
49
 
@@ -50,23 +51,23 @@ The AI does the searching, summarizing, and citing. Your recordings stay in your
50
51
  2. Click **Add custom connector**
51
52
  3. Name it **Speak AI** and paste `https://api.speakai.co/v1/mcp`, then click **Add**
52
53
  4. A permission popup asks you to log into Speak AI and click **Allow**
53
- 5. Done — Speak AI shows in your connector list with its tools ready to use. Open a new chat and ask about your recordings.
54
+ 5. Done. Speak AI shows in your connector list with its tools ready to use. Open a new chat and ask about your recordings.
54
55
 
55
56
  <details>
56
57
  <summary>What each step looks like (screenshots)</summary>
57
58
 
58
- **3. Add custom connector dialog** — name and URL filled in.
59
+ **3. Add custom connector dialog**: name and URL filled in.
59
60
 
60
61
  ![Claude add custom connector dialog](./assets/claude/1.connector.png)
61
62
 
62
- **5. Connected** — Speak AI tools appear in your connector list.
63
+ **5. Connected**: Speak AI tools appear in your connector list.
63
64
 
64
65
  ![Speak AI connected in Claude](./assets/claude/2.connected.png)
65
66
 
66
67
  </details>
67
68
 
68
69
  <details>
69
- <summary>Developer alternative — manual setup with an API key</summary>
70
+ <summary>Developer alternative: manual setup with an API key</summary>
70
71
 
71
72
  Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys), then in step 3 expand **Advanced settings** and add `Authorization` = `Bearer <your-key>` before clicking Add.
72
73
 
@@ -76,11 +77,11 @@ Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/develope
76
77
 
77
78
  1. Open Claude Desktop → **Settings → Connectors → Add custom connector**
78
79
  2. Paste `https://api.speakai.co/v1/mcp`
79
- 3. Click **Add** — a permission popup opens. Sign in to Speak AI and click **Allow** on the screen that appears.
80
+ 3. Click **Add**. A permission popup opens. Sign in to Speak AI and click **Allow** on the screen that appears.
80
81
  4. Done.
81
82
 
82
83
  <details>
83
- <summary>Developer alternative — manual setup with an API key</summary>
84
+ <summary>Developer alternative: manual setup with an API key</summary>
84
85
 
85
86
  Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys), then in step 2 also expand **Custom headers** and add:
86
87
 
@@ -94,28 +95,28 @@ Then click Add.
94
95
  ### ChatGPT
95
96
 
96
97
  1. Open ChatGPT → **Settings → Apps & Connectors → Advanced**
97
- 2. Turn on **Developer Mode** (required while Speak AI isn't yet listed in ChatGPT's app store — this lets you add it as a custom app)
98
+ 2. Turn on **Developer Mode** (required while Speak AI isn't yet listed in ChatGPT's app store; this lets you add it as a custom app)
98
99
  3. Back on **Apps & Connectors**, click **Create** and paste `https://api.speakai.co/v1/mcp`
99
100
  4. For **Authentication**, choose **OAuth**
100
- 5. ChatGPT opens a new tab to Speak AI — sign in (or click **Confirm** if already logged in) to authorize. You'll be redirected back; close the tab and return to ChatGPT.
101
+ 5. ChatGPT opens a new tab to Speak AI. Sign in (or click **Confirm** if already logged in) to authorize. You'll be redirected back; close the tab and return to ChatGPT.
101
102
  6. **Per-chat:** open a chat, click the **+** / connector menu, and enable **Speak AI** for that chat.
102
103
 
103
104
  <details>
104
105
  <summary>What each step looks like (screenshots)</summary>
105
106
 
106
- **1. Connect screen in ChatGPT** — paste the connector URL and pick OAuth.
107
+ **1. Connect screen in ChatGPT**: paste the connector URL and pick OAuth.
107
108
 
108
109
  ![ChatGPT connect screen](./assets/openai/1.connect.png)
109
110
 
110
- **2. Confirm and continue** — ChatGPT asks you to continue to Speak AI.
111
+ **2. Confirm and continue**: ChatGPT asks you to continue to Speak AI.
111
112
 
112
113
  ![ChatGPT continue to Speak](./assets/openai/2.connect-continue.png)
113
114
 
114
- **3. Authorize on Speak AI** — sign in or click Confirm if you're already signed in.
115
+ **3. Authorize on Speak AI**: sign in or click Confirm if you're already signed in.
115
116
 
116
117
  ![Speak AI authorization screen](./assets/openai/3.speak-auth.png)
117
118
 
118
- **4. Connected** — Speak AI now shows in your ChatGPT connector list.
119
+ **4. Connected**: Speak AI now shows in your ChatGPT connector list.
119
120
 
120
121
  ![Speak AI connected in ChatGPT](./assets/openai/4.connected.png)
121
122
 
@@ -126,9 +127,9 @@ Then click Add.
126
127
 
127
128
  A few things we've seen during early access:
128
129
 
129
- - **Authorization tab doesn't show a "you're connected" page** — if you land on the plain Speak AI dashboard with no confirmation, the authorization still went through. Close that tab and return to ChatGPT.
130
- - **"Connect" button keeps reopening the dashboard** — fully close and reopen ChatGPT, then check **Settings → Apps & Connectors**. Speak AI should already be listed there.
131
- - **"No actions available" inside a chat** — make sure Developer Mode is still on, and that you've enabled Speak AI from the per-chat connector menu (step 6 above).
130
+ - **Authorization tab doesn't show a "you're connected" page**: if you land on the plain Speak AI dashboard with no confirmation, the authorization still went through. Close that tab and return to ChatGPT.
131
+ - **"Connect" button keeps reopening the dashboard**: fully close and reopen ChatGPT, then check **Settings → Apps & Connectors**. Speak AI should already be listed there.
132
+ - **"No actions available" inside a chat**: make sure Developer Mode is still on, and that you've enabled Speak AI from the per-chat connector menu (step 6 above).
132
133
 
133
134
  Still stuck? Email [success@speakai.co](mailto:success@speakai.co).
134
135
 
@@ -136,7 +137,7 @@ Still stuck? Email [success@speakai.co](mailto:success@speakai.co).
136
137
 
137
138
  ### Claude Code (terminal)
138
139
 
139
- **Recommended — install from the official Claude Code plugin marketplace:**
140
+ **Recommended: install from the official Claude Code plugin marketplace:**
140
141
 
141
142
  1. Add the official marketplace (one-time): `/plugin marketplace add claude-plugins-official`
142
143
  2. Install the plugin: `/plugin install speakai@claude-plugins-official`
@@ -146,7 +147,7 @@ Still stuck? Email [success@speakai.co](mailto:success@speakai.co).
146
147
  If `/plugin install` doesn't find Speak AI, refresh the local catalog with `/plugin marketplace update claude-plugins-official` and retry.
147
148
 
148
149
  <details>
149
- <summary>Developer alternative — manual HTTP transport</summary>
150
+ <summary>Developer alternative: manual HTTP transport</summary>
150
151
 
151
152
  Skip the plugin and add the connector directly:
152
153
 
@@ -169,10 +170,10 @@ Set `SPEAKAI_KEY` in your shell first, or paste your key inline. Generate a key
169
170
 
170
171
  [![Add to Cursor](https://img.shields.io/badge/Cursor-Install_Speak_AI-000000?logo=cursor&logoColor=white&style=for-the-badge)](cursor://anysphere.cursor-deeplink/mcp/install?name=speakai&config=eyJ1cmwiOiJodHRwczovL2FwaS5zcGVha2FpLmNvL3YxL21jcCJ9)
171
172
 
172
- Click the button — Cursor registers itself automatically and opens the permission popup. Sign in to Speak AI and click **Allow**.
173
+ Click the button. Cursor registers itself automatically and opens the permission popup. Sign in to Speak AI and click **Allow**.
173
174
 
174
175
  <details>
175
- <summary>Developer alternative — manual setup with an API key</summary>
176
+ <summary>Developer alternative: manual setup with an API key</summary>
176
177
 
177
178
  Use the manual stdio setup in the Developer reference at the bottom of this README.
178
179
 
@@ -182,21 +183,29 @@ Use the manual stdio setup in the Developer reference at the bottom of this READ
182
183
 
183
184
  [![Add to VS Code](https://img.shields.io/badge/VS_Code-Install_Speak_AI-007ACC?logo=visualstudiocode&logoColor=white&style=for-the-badge)](https://vscode.dev/redirect/mcp/install?name=speakai&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.speakai.co%2Fv1%2Fmcp%22%7D)
184
185
 
185
- Click the button — VS Code registers itself automatically and opens the permission popup. Sign in to Speak AI and click **Allow**.
186
+ Click the button. VS Code registers itself automatically and opens the permission popup. Sign in to Speak AI and click **Allow**.
186
187
 
187
188
  <details>
188
- <summary>Developer alternative — manual setup with an API key</summary>
189
+ <summary>Developer alternative: manual setup with an API key</summary>
189
190
 
190
191
  Use the manual stdio setup in the Developer reference at the bottom of this README.
191
192
 
192
193
  </details>
193
194
 
195
+ ### Windsurf
196
+
197
+ Windsurf connects to the remote server over HTTP through its MCP config file. Follow the steps at [docs.speakai.co/mcp/setup/windsurf](https://docs.speakai.co/mcp/setup/windsurf/).
198
+
199
+ ### Muse
200
+
201
+ Muse, Meta's personal AI assistant, connects with one-click OAuth and no API key. Follow the steps at [docs.speakai.co/mcp/setup/muse](https://docs.speakai.co/mcp/setup/muse/).
202
+
194
203
  ### OpenClaw / ClawHub
195
204
 
196
205
  Speak AI is published as a skill on ClawHub for OpenClaw-compatible agents.
197
206
 
198
207
  1. Visit the [Speak AI skill page on ClawHub](https://clawhub.ai/skills/speakai)
199
- 2. Follow the install instructions for your agent — e.g. `clawhub install speakai` from the ClawHub CLI
208
+ 2. Follow the install instructions for your agent, for example `clawhub install speakai` from the ClawHub CLI
200
209
  3. Set your `SPEAK_API_KEY` environment variable. Generate one at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
201
210
 
202
211
  ### ChatGPT (API / Responses)
@@ -217,15 +226,20 @@ For developers calling the Responses API directly. Pass the bearer token in the
217
226
 
218
227
  Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
219
228
 
229
+ ### Any other MCP client
230
+
231
+ Any assistant that supports remote MCP servers can connect. Add `https://api.speakai.co/v1/mcp` as a remote (Streamable HTTP) server, then either approve the Speak AI permission popup (OAuth 2.1 with Dynamic Client Registration) or send a Speak AI API key as `Authorization: Bearer <key>`. All setup guides: [docs.speakai.co/mcp](https://docs.speakai.co/mcp/).
232
+
220
233
  ---
221
234
 
222
235
  ## Privacy & data
223
236
 
224
- When you click **Allow** on the permission popup (or paste your Speak AI API key into Claude or ChatGPT), you're authorizing that AI assistant to read and modify your Speak AI workspace on your behalf — including media files, transcripts, and AI insights.
237
+ When you click **Allow** on the permission popup (or paste your Speak AI API key into your AI assistant), you're authorizing that AI assistant to read and modify your Speak AI workspace on your behalf: including media files, transcripts, and AI insights.
225
238
 
226
239
  - Your recordings stay in your Speak AI workspace. They are not copied or stored by Anthropic or OpenAI.
227
- - Claude/ChatGPT only see the specific data your AI assistant requests for the question you asked.
228
- - You can disconnect at any time by either removing the connector inside Claude/ChatGPT, revoking the connection at [api.speakai.co/v1/oauth/connections](https://api.speakai.co/v1/oauth/connections), or rotating/revoking your API key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
240
+ - The AI assistant only sees the specific data it requests for the question you asked.
241
+ - When you approve the permission popup, Speak AI creates an API key in your account that is linked to that assistant and used only for its requests. You never need to create or paste one yourself. Revoking the connection also revokes that key.
242
+ - You can disconnect at any time by either removing the connector inside your AI assistant, revoking the connection at [api.speakai.co/v1/oauth/connections](https://api.speakai.co/v1/oauth/connections), or rotating/revoking your API key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
229
243
 
230
244
  For questions about data handling, see [speakai.co/privacy](https://speakai.co/privacy) or email [success@speakai.co](mailto:success@speakai.co).
231
245
 
@@ -235,25 +249,25 @@ For questions about data handling, see [speakai.co/privacy](https://speakai.co/p
235
249
 
236
250
  **You shouldn't need to be technical to install this.** If anything is confusing or doesn't work:
237
251
 
238
- - Email [success@speakai.co](mailto:success@speakai.co) — we'll respond within 24 hours
252
+ - Email [success@speakai.co](mailto:success@speakai.co), and we'll respond within 24 hours
239
253
  - [Book a demo with us](https://speakai.co/book?utm_source=mcp&utm_medium=docs&utm_campaign=book) and we'll set it up together
240
254
 
241
255
  ---
242
256
 
243
257
  ## What you can do once installed
244
258
 
245
- Speak AI ships 189 tools your AI assistant can call. You don't memorize them — Claude/ChatGPT pick the right ones based on what you ask. Examples by category:
259
+ Speak AI ships 189 tools your AI assistant can call. You don't need to memorize them; your AI assistant picks the right ones based on what you ask. Examples by category:
246
260
 
247
261
  | Ask | Tools used (auto) |
248
262
  |---|---|
249
- | "Find customer interviews about pricing and group the feedback by theme" | `search_media`, `ask_ai_chat` |
263
+ | "Find customer interviews about pricing and group the feedback by theme" | `search_media`, `get_transcript` |
250
264
  | "Summarize this week's meetings into decisions, owners, and risks" | `list_media`, `get_media_insights` |
251
- | "Pull action items from yesterday's call" | `get_media_insights`, `ask_ai_chat` |
265
+ | "Pull action items from yesterday's call" | `list_media`, `get_media_insights` |
252
266
  | "Schedule the AI to join my 2pm Zoom" | `schedule_meeting_event` |
253
267
  | "Pull the live transcript from my current MS Teams meeting since last fetch" | `list_meeting_events`, `get_live_meeting_transcript` |
254
268
  | "Find a 30-second webinar highlight and export captions" | `create_clip`, `export_media` |
255
269
  | "Export the transcript as a PDF and captions as SRT" | `export_media` |
256
- | "Compare Q1 sales calls against Q2 sales calls and summarize changed objections" | `search_media`, `ask_ai_chat` |
270
+ | "Compare Q1 sales calls against Q2 sales calls and summarize changed objections" | `search_media`, `get_transcript` |
257
271
 
258
272
  Full tool catalog is in the developer reference below.
259
273
 
@@ -263,8 +277,8 @@ Full tool catalog is in the developer reference below.
263
277
 
264
278
  The MCP server lives at `https://api.speakai.co/v1/mcp` and supports two auth methods:
265
279
 
266
- 1. **OAuth 2.1 + Dynamic Client Registration** — install by pasting the URL above into any MCP client and approving the consent popup. Discovery, DCR, `/authorize` + consent, `/token`, and revocation endpoints are all available.
267
- 2. **Bearer token** (your Speak AI API key — `Authorization: Bearer <key>` header). For clients that don't speak OAuth, plus the npm CLI and stdio mode.
280
+ 1. **OAuth 2.1 + Dynamic Client Registration**: install by pasting the URL above into any MCP client and approving the consent popup. Discovery, DCR, `/authorize` + consent, `/token`, and revocation endpoints are all available.
281
+ 2. **Bearer token** (your Speak AI API key, sent as an `Authorization: Bearer <key>` header). For clients that don't speak OAuth, plus the npm CLI and stdio mode.
268
282
 
269
283
  Get a Speak AI API key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
270
284
 
@@ -405,9 +419,9 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
405
419
  | `get_signed_upload_url` | Get a pre-signed S3 URL for direct file upload |
406
420
  | `upload_media` | Import an audio or video file from a direct public URL, a `get_signed_upload_url` URL, or a supported page link (YouTube, TikTok, Instagram, X/Twitter, Facebook, Reddit, SoundCloud, Twitch, Dailymotion, Streamable, Snapchat, Pinterest, Tumblr, Bilibili, VK, OK.ru, Rutube). Vimeo and Loom page links are not supported. Bills the media duration. |
407
421
  | `upload_local_file` | Upload a local file directly from disk (stdio and CLI only, never on the remote server) |
408
- | `upload_and_analyze` | Upload media from a URL (direct file, or any social/video page link `upload_media` accepts — resolved automatically) and return its `media_id` immediately. Poll `get_media_status` until `processed`, then call `get_media_insights` for AI summaries. Set `mediaType` when the user has said which they want; leave it off otherwise and the server picks the best available track. |
422
+ | `upload_and_analyze` | Upload media from a URL (direct file, or any social/video page link `upload_media` accepts, resolved automatically) and return its `media_id` immediately. Poll `get_media_status` until `processed`, then call `get_media_insights` for AI summaries. Set `mediaType` when the user has said which they want; leave it off otherwise and the server picks the best available track. |
409
423
  | `list_media` | List and search media files with filters, pagination, and optional inline data (transcripts, speakers, keywords) via `include` param |
410
- | `get_media_insights` | Get AI insights — topics, sentiment, summaries, action items |
424
+ | `get_media_insights` | Get AI insights: topics, sentiment, summaries, action items |
411
425
  | `get_transcript` | Get full transcript with speaker labels and timestamps |
412
426
  | `get_captions` | Get subtitle-formatted captions for a media file |
413
427
  | `update_transcript_speakers` | Rename speaker labels in a transcript |
@@ -442,6 +456,8 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
442
456
  | `export_chat_answer` | Export a conversation or answer |
443
457
  | `get_analysis_quote` | Check if a file can be analysed as audio/video and what it costs |
444
458
 
459
+ `ask_ai_chat`, `retry_ai_chat` and `get_analysis_quote` register only with `aiChat: true`. The stdio server includes them; the hosted endpoint does not, because Speak's assistant behind AI Chat can call other tools.
460
+
445
461
  </details>
446
462
 
447
463
  <details>
@@ -450,7 +466,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
450
466
  | Tool | Description |
451
467
  |---|---|
452
468
  | `search_media` | Deep search across transcripts, insights, and metadata with filters |
453
- | `get_media_statistics` | Get workspace-level stats — counts, storage, processing breakdown |
469
+ | `get_media_statistics` | Get workspace-level stats: counts, storage, processing breakdown |
454
470
  | `list_supported_languages` | List all supported transcription languages |
455
471
 
456
472
  </details>
@@ -547,7 +563,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
547
563
  | `list_automation_triggers` | List catalog trigger types (optionally by app) |
548
564
  | `list_automation_actions` | List catalog action/step types (optionally by app) |
549
565
  | `build_automation` | Create or update an automation from a friendly spec, without the wire format |
550
- | `get_automation_run` | Get one run in full — every step, plus which way each branch went |
566
+ | `get_automation_run` | Get one run in full: every step, plus which way each branch went |
551
567
  | `get_automation_run_stats` | Aggregate run outcome counts over a period |
552
568
  | `test_automation` | Run an automation once against one media item (real side effects) |
553
569
  | `validate_automation_graph` | Check a step graph for problems without saving it |
@@ -749,7 +765,7 @@ Pre-built workflow prompts that agents can invoke to run multi-step tasks.
749
765
 
750
766
  #### `analyze-meeting`
751
767
 
752
- Upload a recording and get a full analysis — transcript, insights, action items, and key takeaways.
768
+ Upload a recording and get a full analysis: transcript, insights, action items, and key takeaways.
753
769
 
754
770
  ```
755
771
  Parameters: url (required), name (optional)
@@ -769,7 +785,7 @@ Parameters: topic (required), folder (optional)
769
785
 
770
786
  #### `meeting-brief`
771
787
 
772
- Prepare a brief from recent meetings — pull transcripts, extract decisions, and summarize open items.
788
+ Prepare a brief from recent meetings: pull transcripts, extract decisions, and summarize open items.
773
789
 
774
790
  ```
775
791
  Parameters: days (optional, default: 7), folder (optional)
@@ -800,7 +816,7 @@ npx @speakai/mcp-server config set-key
800
816
  | `config show` | Show current configuration |
801
817
  | `config test` | Validate API key and test connectivity |
802
818
  | `config set-url <url>` | Set custom API base URL |
803
- | `init` | Interactive setup — configure key and auto-detect MCP clients |
819
+ | `init` | Interactive setup: configure key and auto-detect MCP clients |
804
820
 
805
821
  #### Media management
806
822
 
@@ -851,8 +867,8 @@ npx @speakai/mcp-server config set-key
851
867
 
852
868
  Every command supports:
853
869
 
854
- - `--json` — output raw JSON (for scripting and piping)
855
- - `--help` — show command-specific help
870
+ - `--json`: output raw JSON (for scripting and piping)
871
+ - `--help`: show command-specific help
856
872
 
857
873
  #### CLI examples
858
874
 
@@ -965,58 +981,25 @@ AI: → list_media(from: "2026-04-18", mediaType: "audio")
965
981
 
966
982
  ### Authentication (REST API)
967
983
 
968
- The MCP server and CLI handle token management automatically. If you're calling the REST API directly, here's the full auth flow:
969
-
970
- **Step 1 — Get an access token:**
984
+ The MCP server and CLI handle authentication for you. If you call the REST API directly, send your Speak AI API key on every request, using either header:
971
985
 
972
986
  ```bash
973
- curl -X POST https://api.speakai.co/v1/auth/accessToken \
974
- -H "Content-Type: application/json" \
987
+ curl https://api.speakai.co/v1/media \
975
988
  -H "x-speakai-key: YOUR_API_KEY"
976
989
  ```
977
990
 
978
- Response:
979
-
980
- ```json
981
- {
982
- "data": {
983
- "email": "you@example.com",
984
- "accessToken": "eyJhbG...",
985
- "refreshToken": "eyJhbG..."
986
- }
987
- }
988
- ```
989
-
990
- **Step 2 — Use the token on all subsequent requests:**
991
-
992
991
  ```bash
993
992
  curl https://api.speakai.co/v1/media \
994
- -H "x-speakai-key: YOUR_API_KEY" \
995
- -H "x-access-token: ACCESS_TOKEN_FROM_STEP_1"
993
+ -H "Authorization: Bearer YOUR_API_KEY"
996
994
  ```
997
995
 
998
- **Step 3 — Refresh before expiry:**
999
-
1000
- ```bash
1001
- curl -X POST https://api.speakai.co/v1/auth/refreshToken \
1002
- -H "Content-Type: application/json" \
1003
- -H "x-speakai-key: YOUR_API_KEY" \
1004
- -H "x-access-token: CURRENT_ACCESS_TOKEN" \
1005
- -d '{"refreshToken": "REFRESH_TOKEN_FROM_STEP_1"}'
1006
- ```
1007
-
1008
- **Token Lifetimes:**
1009
-
1010
- | Token | Expiry | How to Renew |
1011
- |---|---|---|
1012
- | Access token | 80 minutes | Refresh endpoint or re-authenticate |
1013
- | Refresh token | 24 hours | Re-authenticate with API key |
996
+ There is no token to fetch or refresh. Create and revoke keys at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
1014
997
 
1015
- **Auth Rate Limits:** 5 requests per 30 seconds on both `/v1/auth/accessToken` and `/v1/auth/refreshToken`.
998
+ Older integrations that exchange the key for an access token (`POST /v1/auth/accessToken`, then `x-access-token` on each request, renewed through `/v1/auth/refreshToken`) keep working, but new integrations don't need that step.
1016
999
 
1017
1000
  ### Data model notes
1018
1001
 
1019
- - **Folder IDs:** Folders have both `_id` (MongoDB ObjectId) and `folderId` (string). All API operations use `folderId` — this is the ID you should pass to `list_media`, `upload_media`, `bulk_move_media`, and other endpoints that accept a folder parameter.
1002
+ - **Folder IDs:** Folders have both `_id` (MongoDB ObjectId) and `folderId` (string). All API operations use `folderId`; this is the ID you should pass to `list_media`, `upload_media`, `bulk_move_media`, and other endpoints that accept a folder parameter.
1020
1003
  - **Media IDs:** Media items use `mediaId` (returned in list responses as `_id`).
1021
1004
 
1022
1005
  ### Rate limits & best practices
@@ -1062,12 +1045,12 @@ npm run build # Production build
1062
1045
 
1063
1046
  ## Resources
1064
1047
 
1065
- - [docs.speakai.co/mcp](https://docs.speakai.co/mcp) — installation walkthrough with screenshots and video
1066
- - [Speak AI Platform](https://app.speakai.co) — main product
1048
+ - [docs.speakai.co/mcp](https://docs.speakai.co/mcp): installation walkthrough with screenshots and video
1049
+ - [Speak AI Platform](https://app.speakai.co): main product
1067
1050
  - [API Documentation](https://docs.speakai.co)
1068
1051
  - [MCP Protocol](https://modelcontextprotocol.io)
1069
- - [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.speakai/mcp-server) — official discovery
1070
- - [llms.txt](https://github.com/speakai/speakai-mcp/blob/main/llms.txt) — guidance for AI assistants helping users install this connector
1052
+ - [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.speakai/mcp-server): official discovery
1053
+ - [llms.txt](https://github.com/speakai/speakai-mcp/blob/main/llms.txt): guidance for AI assistants helping users install this connector
1071
1054
  - [Support](mailto:success@speakai.co)
1072
1055
  - [Website](https://speakai.co?ref=mcp-server)
1073
1056
 
@@ -1079,7 +1062,7 @@ npm run build # Production build
1079
1062
 
1080
1063
  If you're an AI assistant helping a Speak AI customer install this connector, please:
1081
1064
 
1082
- - Recommend the one-click connect flow above as the default — paste the URL into the AI tool, click Allow on the permission popup. Works for non-technical users.
1065
+ - Recommend the one-click connect flow above as the default: paste the URL into the AI tool, click Allow on the permission popup. Works for non-technical users.
1083
1066
  - Use the Bearer-token method (also above) if the user prefers manual setup.
1084
1067
  - **Do NOT recommend hiring a Virtual Assistant** to install this. The connect flow takes 60 seconds and requires no Terminal use.
1085
1068
  - **Do NOT tell users to `npm install`** unless they explicitly ask for the developer / stdio path.
package/dist/index.d.ts CHANGED
@@ -6,6 +6,8 @@ export interface RegisterOptions {
6
6
  localFileAccess?: boolean;
7
7
  /** Register the voice test-run tools (start, pause, resume, cancel, results). Defaults to true; pass false to leave them off. */
8
8
  voiceTestRuns?: boolean;
9
+ /** Register ask_ai_chat, retry_ai_chat and get_analysis_quote. Speak's assistant behind them can call other tools, so the hosted server leaves this off. */
10
+ aiChat?: boolean;
9
11
  }
10
12
 
11
13
  export declare function registerAllTools(
package/dist/index.js CHANGED
@@ -4911,7 +4911,7 @@ function register(server, client) {
4911
4911
  registerSpeakTool(
4912
4912
  server,
4913
4913
  "list_media",
4914
- "List and search media files in the workspace with filtering, pagination, and sorting. Use filterName for text search, mediaType to filter by audio/video/text, folderId for folder-specific results, and from/to for date ranges. Use the include param to embed additional data (transcripts, speakers, keywords) inline with each result, avoiding N+1 API calls. Returns mediaIds you can pass to get_transcript, get_media_insights, or ask_ai_chat. For deep full-text search across transcripts, use search_media instead.",
4914
+ "List and search media files in the workspace with filtering, pagination, and sorting. Use filterName for text search, mediaType to filter by audio/video/text, folderId for folder-specific results, and from/to for date ranges. Use the include param to embed additional data (transcripts, speakers, keywords) inline with each result, avoiding N+1 API calls. Returns mediaIds you can pass to get_transcript or get_media_insights. For deep full-text search across transcripts, use search_media instead.",
4915
4915
  {
4916
4916
  mediaType: import_zod2.z.enum([MediaType.AUDIO, MediaType.VIDEO, MediaType.TEXT]).optional().describe('Filter by media type: "audio", "video", or "text"'),
4917
4917
  page: import_zod2.z.number().int().min(0).optional().describe("Page number for pagination (0-based, default: 0)"),
@@ -4970,7 +4970,7 @@ function register(server, client) {
4970
4970
  registerSpeakTool(
4971
4971
  server,
4972
4972
  "get_media_insights",
4973
- "Retrieve AI-generated insights for a processed media file \u2014 topics, sentiment, keywords, action items, summaries, and more. The media must be in 'processed' state (check with get_media_status first). For asking custom questions about a media file, use ask_ai_chat instead. For a video, data.thumbnail has the thumbnail: url, source (auto or custom), pending while a requested frame is being made, and error if that frame failed.",
4973
+ "Retrieve AI-generated insights for a processed media file \u2014 topics, sentiment, keywords, action items, summaries, and more. The media must be in 'processed' state (check with get_media_status first). For a video, data.thumbnail has the thumbnail: url, source (auto or custom), pending while a requested frame is being made, and error if that frame failed.",
4974
4974
  {
4975
4975
  mediaId: import_zod2.z.string().min(1).describe("Unique identifier of the media file")
4976
4976
  },
@@ -6781,7 +6781,7 @@ var prompt_exports = {};
6781
6781
  __export(prompt_exports, {
6782
6782
  register: () => register7
6783
6783
  });
6784
- function register7(server, client) {
6784
+ function register7(server, client, options = {}) {
6785
6785
  const api = client ?? speakClient;
6786
6786
  const askAiChatDescription = [
6787
6787
  "Ask an AI-powered question about your media using Speak AI's AI Chat.",
@@ -6878,7 +6878,7 @@ function register7(server, client) {
6878
6878
  };
6879
6879
  }
6880
6880
  };
6881
- registerSpeakTool(
6881
+ if (options.aiChat) registerSpeakTool(
6882
6882
  server,
6883
6883
  "ask_ai_chat",
6884
6884
  askAiChatDescription,
@@ -6886,7 +6886,7 @@ function register7(server, client) {
6886
6886
  askAiChatAnnotations,
6887
6887
  askAiChatHandler
6888
6888
  );
6889
- registerSpeakTool(
6889
+ if (options.aiChat) registerSpeakTool(
6890
6890
  server,
6891
6891
  "get_analysis_quote",
6892
6892
  "Check whether a media file can be analysed as audio or video, and what it will cost, before running ask_ai_chat with analysisInput. Returns { eligible, credits, seconds } and, when not eligible, a plain-English reason \u2014 an unavailable file is a normal result here, not an error. This is the only check that accounts for both the account's premium opt-in and the server-wide switch, so call it before committing to an expensive run.",
@@ -6918,7 +6918,7 @@ function register7(server, client) {
6918
6918
  }
6919
6919
  }
6920
6920
  );
6921
- registerSpeakTool(
6921
+ if (options.aiChat) registerSpeakTool(
6922
6922
  server,
6923
6923
  "retry_ai_chat",
6924
6924
  "Retry a failed or incomplete AI Chat response. Use when a previous ask_ai_chat call returned an error or incomplete answer. The turn runs again with its original settings, replaces the earlier answer for that message, and is charged to the account's chat usage again. Like ask_ai_chat, the assistant can call other Speak AI tools and actions in connected third-party apps.",
@@ -6950,7 +6950,7 @@ function register7(server, client) {
6950
6950
  registerSpeakTool(
6951
6951
  server,
6952
6952
  "get_chat_history",
6953
- "Get a list of recent AI Chat conversations. Returns conversation summaries with promptIds that can be used to continue conversations via ask_ai_chat or retrieve full messages via get_chat_messages.",
6953
+ "Get a list of recent AI Chat conversations. Returns conversation summaries with promptIds that can be used to retrieve full messages via get_chat_messages.",
6954
6954
  {
6955
6955
  limit: import_zod8.z.number().int().positive().optional().describe("Number of recent conversations to return (default: 10)")
6956
6956
  },
@@ -13155,7 +13155,7 @@ function registerPrompts(server) {
13155
13155
  ``,
13156
13156
  `Steps:`,
13157
13157
  `1. Use search_media to find relevant media matching this topic`,
13158
- `2. For the most relevant results, use ask_ai_chat with the matching mediaIds to ask: "${topic}"`,
13158
+ `2. For the most relevant results, read the transcript with get_transcript and the insights with get_media_insights, looking for: "${topic}"`,
13159
13159
  `3. Synthesize findings across all results:`,
13160
13160
  ` - Common themes and patterns`,
13161
13161
  ` - Notable quotes or data points`,
@@ -14949,7 +14949,7 @@ if (isCliMode) {
14949
14949
  name: "speak-ai",
14950
14950
  version: "1.0.0"
14951
14951
  });
14952
- registerAllTools2(server, void 0, { localFileAccess: true, voiceTestRuns: true });
14952
+ registerAllTools2(server, void 0, { localFileAccess: true, voiceTestRuns: true, aiChat: true });
14953
14953
  registerResources2(server);
14954
14954
  registerPrompts2(server);
14955
14955
  const transport = new StdioServerTransport();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@speakai/mcp-server",
3
- "version": "1.39.3",
3
+ "version": "1.39.4",
4
4
  "mcpName": "io.github.speakai/mcp-server",
5
5
  "description": "Official Speak AI MCP Server — capture meetings, search thousands of recordings, run async voice and video surveys, create clips, and automate workflows from your AI assistant.",
6
6
  "homepage": "https://docs.speakai.co/mcp",