MCP tools
Every tool the Specala AI MCP server exposes to AI assistants — what each one accepts and the REST endpoint it maps to, with parameters and examples.
The Specala AI MCP server exposes a set of tools. You don't call these directly — your AI assistant does, based on what you ask. This page documents what each tool accepts so you understand (and can guide) the assistant's behaviour.
See MCP Quickstart to connect the server. Each tool maps to a REST endpoint under the hood.
Remote vs local server
Specala AI ships two variants: the remote connector (https://mcp.specala.ai/mcp, OAuth
sign-in, recommended) and the local npm server (API key). The tools are the same, with one
difference: anything that touches your disk — output_path, specala_bulk_export and
specala_upload_file — is available only on the local server; the remote connector returns
content directly in the chat.
specala_list_projects
List the projects in the workspace, each with its UUID and name. The assistant uses this to discover
the project_id it needs before filtering transcriptions by project. Takes no parameters.
→ REST: GET /projects
specala_list_transcriptions
Find transcriptions with titles, summaries, speakers and topics. The assistant uses this first to locate the right meetings before fetching full text.
| Parameter | Type | Description |
|---|---|---|
project_id | string | Filter by project UUID (from specala_list_projects). |
language | string | Language code (ru, en, …). |
date_from | string | From date, YYYY-MM-DD. |
date_to | string | To date, YYYY-MM-DD. |
sort | string | created_at, -created_at, duration, -duration. |
limit | number | Max results per page (default 20, max 100). |
offset | number | Pagination offset. |
→ REST: GET /transcriptions
specala_get_transcription
Get the full transcript with speaker labels, timestamps and AI reports for one meeting.
| Parameter | Type | Description |
|---|---|---|
id | string | Transcription UUID (required). |
→ REST: GET /transcriptions/{id}
specala_export_transcription
Save one transcription as a .md or .txt file.
| Parameter | Type | Description |
|---|---|---|
id | string | Transcription UUID (required). |
format | "md" | "txt" | Export format (default md). |
output_path | string | Absolute file path to write to. Local server only. |
output_path saves tokens
When output_path is set, the server writes the file directly to disk and returns only a short
confirmation — the full transcript never enters the conversation. Strongly preferred for long
meetings.
→ REST: GET /transcriptions/{id}/export
specala_bulk_export
Local server only — the ZIP is unpacked onto your disk, which the remote connector can't do.
Export many transcriptions at once. The server returns a ZIP; the MCP server unpacks it into your
output_dir. One API call regardless of count (1–100).
| Parameter | Type | Description |
|---|---|---|
ids | string[] | 1–100 transcription UUIDs (required). |
format | "md" | "txt" | Export format (default md). |
output_dir | string | Absolute directory to save files into (required). |
→ REST: POST /transcriptions/export
specala_upload_file
Local server only — the server streams a file from your disk, which the remote connector can't
do. Uploads an audio/video file (up to 2 GB) for transcription and returns the transcription UUID
right away; the assistant then polls specala_get_transcription until it's completed.
Requires a key created with Allow file uploads — read-only keys get upload_scope_required
(the tool will tell the assistant how to fix that).
| Parameter | Type | Description |
|---|---|---|
file_path | string | Absolute path to the media file (required). |
language | string | Spoken language hint, e.g. en. |
project_id | string | Attach to a project (UUID from specala_list_projects). |
ai_metadata | boolean | Also generate the AI layer (summary, reports). Default false — the assistant usually analyses the transcript itself. |
→ REST: POST /transcriptions
A typical assistant flow
For "Summarise my calls with Acme this month and save them to ~/notes", the assistant chains the tools on its own:
Delete transcription
DELETE /transcriptions/{id} — permanently delete a transcription, its transcript text, AI reports and stored audio.
Errors & rate limits
HTTP status codes the Specala AI API returns (401, 403, 422, 429, 5xx), the JSON error shape, what triggers each one, and how to handle rate limits.