Speko MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   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.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'spekomcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Speko MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'spekomcp_agents_list',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

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

What you can do

Connect this agent connector to let your agent:

• List voices, sessions, scenarios runs — List the Speko TTS voice catalog: voices (vendor, id, name) plus TTS providers with their models
• Get usage summary, sessions transcript, sessions recording — Get workspace usage, managed cost and current balance
• Create share cards, sessions phone, sessions — Create a public share card for an agent build
• Detach scenarios — Detach a library scenario from one agent
• Attach scenarios — Attach a library scenario to an agent so the reliability gate drives it there
• Archive scenarios — Archive a scenario — the only lifecycle transition there is

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.

spekomcp_agent_access_oauth_grant_revoke#Revoke one OAuth client grant for the current user and workspace. consentId is the id field from agent_access.overview's oauthGrants array, not the client id. Requires speko:credentials, a scope not used elsewhere on this surface.1 param▾

Revoke one OAuth client grant for the current user and workspace. consentId is the id field from agent_access.overview's oauthGrants array, not the client id. Requires speko:credentials, a scope not used elsewhere on this surface.

NameTypeRequiredDescription

consentIdstringrequiredThe grant/consent id to revoke, taken from the "id" field of an entry in agent_access.overview's oauthGrants array. This is not the OAuth client id. Between 1 and 200 characters.

spekomcp_agent_access_overview#List OAuth client grants and product API keys for the current workspace control plane. oauthGrants carry the scopes each connected client holds; apiKeys carry a revoked flag and lastUsedAt (null if never used). Pass an oauthGrants id to agent_access.oauth_grant.revoke to remove one. OAuth-user principals only.0 params▾

List OAuth client grants and product API keys for the current workspace control plane. oauthGrants carry the scopes each connected client holds; apiKeys carry a revoked flag and lastUsedAt (null if never used). Pass an oauthGrants id to agent_access.oauth_grant.revoke to remove one. OAuth-user principals only.

spekomcp_agents_apply_prompt_fix#Deploy a revised system prompt as a NEW agent version. Takes the current live config, swaps the prompt, and deploys — which auto-enqueues a version-stamped re-test, closing the fail → suggest → apply → re-test loop. Send the FULL prompt, not a diff. Requires the agent to already have a deployed version.3 params▾

Deploy a revised system prompt as a NEW agent version. Takes the current live config, swaps the prompt, and deploys — which auto-enqueues a version-stamped re-test, closing the fail → suggest → apply → re-test loop. Send the FULL prompt, not a diff. Requires the agent to already have a deployed version.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the Speko agent to deploy the revised system prompt to, as returned by agents.create or agents.list. The agent must already have a deployed version.

system_promptstringrequiredThe full replacement system prompt to deploy, up to 24000 characters. Send the complete prompt text, not a diff against the current one.

based_on_runstringoptionalThe run this fix answers — recorded in the new version source.

spekomcp_agents_apply_stack_fix#Re-pin ONE pipeline layer (stt, llm or tts) to a different provider and deploy that as a new agent version — the fix that is not a prompt change. Every other layer and config key is carried forward. Auto-enqueues a re-test like agents.apply_prompt_fix.4 params▾

Re-pin ONE pipeline layer (stt, llm or tts) to a different provider and deploy that as a new agent version — the fix that is not a prompt change. Every other layer and config key is carried forward. Auto-enqueues a re-test like agents.apply_prompt_fix.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the Speko agent to re-pin a pipeline layer for, as returned by agents.create or agents.list.

layerstringrequiredWhich pipeline layer to re-pin: stt (speech-to-text), llm (language model), or tts (text-to-speech). Every other layer is carried forward unchanged.

providerstringrequiredThe provider id to pin the chosen layer to, replacing whatever provider it currently uses on that layer.

based_on_runstringoptionalOptional id of the eval run this stack fix addresses, recorded on the new agent version for traceability.

spekomcp_agents_calls_list#List recent calls for an agent.4 params▾

List recent calls for an agent.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent whose recent calls to list, as returned by agents.create or agents.list.

cursorstringoptionalPagination cursor: an ISO timestamp cursor from a previous response, used to fetch the next page of calls. Omit to start from the most recent call.

limitintegeroptionalMaximum number of calls to return in this page. Omit to use the server's default page size.

sincestringoptionalOptional ISO 8601 lower-bound timestamp; only calls made at or after this time are returned. Omit for no lower bound.

spekomcp_agents_config_structure_get#Read the agent's LIVE system prompt back as a structured decision view — its goals, the rules it follows, and its conditional branches, plus a best-effort flow. Derived on demand, not stored. Returns status "empty" when the agent has no prompt yet.1 param▾

Read the agent's LIVE system prompt back as a structured decision view — its goals, the rules it follows, and its conditional branches, plus a best-effort flow. Derived on demand, not stored. Returns status "empty" when the agent has no prompt yet.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the Speko agent whose live system prompt to read back as a structured decision view, as returned by agents.create or agents.list.

spekomcp_agents_create#Create a Speko agent. The agent is pinned to the failover stack matching intent.optimizeFor (quality / latency / cost) and intent.region. Stack tiers and their components for a given description are reported by preview_stacks.1 param▾

Create a Speko agent. The agent is pinned to the failover stack matching intent.optimizeFor (quality / latency / cost) and intent.region. Stack tiers and their components for a given description are reported by preview_stacks.

NameTypeRequiredDescription

bodyobjectrequiredJSON body for POST /v1/agents. Required shape: {name: string, systemPrompt: string, intent: {language: string, optimizeFor?: 'latency'|'quality'|'cost', region?: string}}. intent.optimizeFor selects which failover stack the server pins: 'quality' is the premium tier, 'latency' the fastest tier, 'cost' the cheapest. intent.region defaults to 'usa'. The intent field is routing metadata describing how to route the agent's audio, not a use-case string. The stack tiers available for a given description, and their stt/llm/tts components, are reported by preview_stacks. Optional turnHandling ({profile?: 'conversational'|'ivr', dtmfToolDescription?: string, onMachine?: string, amdPrompt?: string, ...}). Setting profile to 'ivr' arms the agent's keypad tool (send_dtmf) for the whole call; without it, the keypad tool only arms when answering-machine detection classifies the call as an automated menu mid-call.

spekomcp_agents_delete#Delete one Speko agent.1 param▾

Delete one Speko agent.

NameTypeRequiredDescription

agent_idstringrequiredAgent id.

spekomcp_agents_deploy#Deploy a SessionConfig as a new immutable agent version.4 params▾

Deploy a SessionConfig as a new immutable agent version.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to deploy a new version for.

session_configobjectrequiredThe Speko SessionConfig to deploy as this agent's new immutable version — the same shape used when creating a session (voice, systemPrompt, firstMessage, llm sampling options, ttsOptions, sttOptions, backgroundAudio, constraints, and related fields). Deploying creates a brand-new version number; calls already in progress keep running on the version they started with. Example: {"voice": "warm-female-1", "systemPrompt": "You are a helpful restaurant host.", "firstMessage": "Thanks for calling, how can I help?"}

briefing_markdownstringoptionalOptional markdown briefing notes to attach to this deployed version, e.g. release notes for a reviewer.

sourcestringoptionalOptional label identifying where this deploy came from. Defaults to an MCP-upstream label when omitted.

spekomcp_agents_duplicate#Duplicate an agent and its copyable tools, knowledge, evaluations, version, and graph. The copy carries the source voice and turnHandling settings forward unchanged. Check the returned warnings array. TOOL_AUTH_REQUIRED means a copied tool is registered on the new agent but needs its credentials or auth headers reconnected, so a duplicated agent can show a tool as present while it silently fails until that happens. WEBHOOK_AUTH_REQUIRED is a separate case: it applies to lifecycle webhooks (preCall, postCall, status, analysis, recording), not tools, and those are copied already disabled rather than left silently broken, so each one needs its auth fixed and then re-enabled by hand. INTEGRATION_DISCONNECTED and GRAPH_NOT_COPIED name the other two things that did not carry over.2 params▾

Duplicate an agent and its copyable tools, knowledge, evaluations, version, and graph. The copy carries the source voice and turnHandling settings forward unchanged. Check the returned warnings array. TOOL_AUTH_REQUIRED means a copied tool is registered on the new agent but needs its credentials or auth headers reconnected, so a duplicated agent can show a tool as present while it silently fails until that happens. WEBHOOK_AUTH_REQUIRED is a separate case: it applies to lifecycle webhooks (preCall, postCall, status, analysis, recording), not tools, and those are copied already disabled rather than left silently broken, so each one needs its auth fixed and then re-enabled by hand. INTEGRATION_DISCONNECTED and GRAPH_NOT_COPIED name the other two things that did not carry over.

NameTypeRequiredDescription

namestringrequiredName for the new duplicated agent (1-120 characters).

source_agent_idstringrequiredId of the existing Speko agent to duplicate. Its copyable tools, knowledge bases, evaluations, latest version, and graph are copied onto the new agent, and the copy's voice and turnHandling settings carry over unchanged from the source.

spekomcp_agents_evals_character_set#Set or clear JUST the simulated-caller character on one test case. Merged into the existing input_payload without touching its other keys — this is the safe way to change a persona. Pass null to clear it back to a clean caller.3 params▾

Set or clear JUST the simulated-caller character on one test case. Merged into the existing input_payload without touching its other keys — this is the safe way to change a persona. Pass null to clear it back to a clean caller.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent that owns the test case.

characterstringrequiredThe simulated-caller persona preset to merge into this case's input_payload, or null to clear it back to a plain caller with no persona. Choices: fast_talker, interrupter, hesitant, noisy_line, rambler, impatient, script_reader, multitasker, rapid_interrupter, faint_line. This is merged in without touching the case's other input_payload keys, unlike agents.evals.update which replaces the whole payload.

eval_idstringrequiredId of the test case (eval) whose simulated-caller character to set, as returned by agents.evals.create or agents.evals.list.

spekomcp_agents_evals_create#Create an eval for an agent.2 params▾

Create an eval for an agent.

NameTypeRequiredDescription

agent_idstringrequiredAgent id.

bodyobjectrequiredJSON body for POST /v1/agents/{id}/evals. Required shape: {name: string (1-160 chars), expected_behavior: string}. Optional: description (string <=1024), assertion_kind ('contains_phrase'|'tool_called'|'language_switched'|'within_latency'|'no_hallucination'|'custom', default 'custom'), assertion_config (object, default {}), input_kind ('transcript'|'audio_url'|'assertion_only', default 'transcript'), input_payload (object, default {}), source_call_id (uuid of the call to promote), block_deploy_on_fail (bool, default true).

spekomcp_agents_evals_delete#Delete one test case. Historical runs survive — the run rows reference the case through a nullable column, so the track record is not destroyed with the case.2 params▾

Delete one test case. Historical runs survive — the run rows reference the case through a nullable column, so the track record is not destroyed with the case.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent that owns the test case to delete.

eval_idstringrequiredId of the test case (eval) to permanently delete, as returned by agents.evals.create or agents.evals.list. Historical runs of this case are kept.

spekomcp_agents_evals_generate#Author test cases for an agent from its own configuration — system prompt, intent, tools, knowledge-base titles and first message — using the scenario generator. Returns the generated cases WITHOUT saving by default; pass persist:true to also insert them as test cases. Calls an LLM, so it is slower than the other actions here.2 params▾

Author test cases for an agent from its own configuration — system prompt, intent, tools, knowledge-base titles and first message — using the scenario generator. Returns the generated cases WITHOUT saving by default; pass persist:true to also insert them as test cases. Calls an LLM, so it is slower than the other actions here.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to generate test-case scenarios for, based on its current system prompt, intent, tools, knowledge-base titles, and first message.

persistbooleanrequiredWhether to also insert the generated test cases into this agent's eval suite. When false (the default), the cases are generated and returned only, without being saved, so you can preview them first. When true, the returned cases are also created as test cases, the same as calling agents.evals.create for each one.

spekomcp_agents_evals_list#List evals for an agent.1 param▾

List evals for an agent.

NameTypeRequiredDescription

agent_idstringrequiredAgent id.

spekomcp_agents_evals_run#Run one agent eval.2 params▾

Run one agent eval.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the Speko agent that owns the eval, as returned by agents.create or agents.list.

eval_idstringrequiredUnique identifier of the eval to run, as returned by agents.evals.create or agents.evals.list.

spekomcp_agents_evals_runs_list#The five most recent runs of ONE test case, newest first, each with the verdict in its result. Poll this after agents.evals.run to watch a case settle.2 params▾

The five most recent runs of ONE test case, newest first, each with the verdict in its result. Poll this after agents.evals.run to watch a case settle.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent that owns the test case.

eval_idstringrequiredId of the test case (eval) whose recent runs to list, as returned by agents.evals.create or agents.evals.list.

spekomcp_agents_evals_runs_suggest_fix#Ask for a minimal system-prompt revision that would make a FAILED run pass. The failures are extracted from the run itself, so you only need the run id. Read-only — it proposes, it does not deploy; pass the result to agents.apply_prompt_fix to ship it. Returns status "no_fix_needed" when the run has no failures.2 params▾

Ask for a minimal system-prompt revision that would make a FAILED run pass. The failures are extracted from the run itself, so you only need the run id. Read-only — it proposes, it does not deploy; pass the result to agents.apply_prompt_fix to ship it. Returns status "no_fix_needed" when the run has no failures.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent that owns the eval run to analyze.

run_idstringrequiredId of the specific eval run whose failures should be analyzed for a minimal system-prompt fix. Returns status "no_fix_needed" if the run has no failures.

spekomcp_agents_evals_suggest_prompt_fix#Ask for a minimal system-prompt revision from failures you supply yourself, when the failures did not come from one stored run. Prefer agents.evals.runs.suggest_fix when you have a run id. Read-only — it proposes, it does not deploy.2 params▾

Ask for a minimal system-prompt revision from failures you supply yourself, when the failures did not come from one stored run. Prefer agents.evals.runs.suggest_fix when you have a run id. Read-only — it proposes, it does not deploy.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the Speko agent whose failing scenarios you want a minimal prompt fix for, as returned by agents.create or agents.list.

failuresarrayrequired1 to 20 scenario failures to derive a prompt fix from. Each entry needs the scenario name and the reason it failed; expected_behavior is optional context on what should have happened instead.

spekomcp_agents_evals_trends_get#Pass-rate over time for one agent, as a contiguous zero-filled series plus window totals. Manual test calls are excluded — they are hardcoded-pass and would inflate the rate. Out-of-range `days` clamps rather than erroring.3 params▾

Pass-rate over time for one agent, as a contiguous zero-filled series plus window totals. Manual test calls are excluded — they are hardcoded-pass and would inflate the rate. Out-of-range `days` clamps rather than erroring.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to get the eval pass-rate trend for.

bucketstringrequiredTime bucket to group the pass-rate series by: day or week. Defaults to day.

daysintegerrequiredNumber of days of history to include in the trend, from 1 to 365. Out-of-range values are clamped rather than rejected. Defaults to 30.

spekomcp_agents_evals_update#Partially update one test case. Only the fields you send are written; omitted fields are left untouched. `description` and `source_call_id` accept null to clear them. Sending `input_payload` replaces it wholesale, so read the case first if you mean to keep its other keys — to change only the caller character use agents.evals.character.set instead.11 params▾

Partially update one test case. Only the fields you send are written; omitted fields are left untouched. `description` and `source_call_id` accept null to clear them. Sending `input_payload` replaces it wholesale, so read the case first if you mean to keep its other keys — to change only the caller character use agents.evals.character.set instead.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent that owns the test case to update.

eval_idstringrequiredId of the test case (eval) to update, as returned by agents.evals.create or agents.evals.list.

assertion_configobjectoptionalNew assertion_config object matching the chosen assertion_kind (e.g. the phrase to look for, or a latency threshold). Sending this replaces the whole object; omit to leave it unchanged.

assertion_kindstringoptionalNew assertion_kind for how this case is scored: contains_phrase, tool_called, language_switched, within_latency, no_hallucination, custom, or voicemail_handled. Omit to leave it unchanged.

block_deploy_on_failbooleanoptionalNew block_deploy_on_fail setting: whether a failing run of this case blocks agents.deploy. Omit to leave it unchanged.

descriptionstringoptionalNew description for the test case, up to 1024 characters. Explicitly sending null clears an existing description; omitting the field leaves it unchanged.

expected_behaviorstringoptionalNew expected_behavior text describing what a passing run must do. Omit to leave it unchanged.

input_kindstringoptionalNew input_kind describing what is scored: transcript, audio_url, assertion_only, or phone_call. Omit to leave it unchanged.

input_payloadobjectoptionalNew input_payload for the chosen input_kind (e.g. a transcript array or an audio URL). Sending this REPLACES the whole object, so read the case first if you want to keep its other keys — to change only the caller persona use agents.evals.character.set instead.

namestringoptionalNew name for the test case (1-160 characters). Omit to leave the name unchanged.

source_call_idstringoptionalId of a call to associate with this test case as its promoted source, or null to clear the association. Omit to leave it unchanged.

spekomcp_agents_get#Get one agent and its complete editable configuration, including voice, turnHandling (profile, dtmfToolDescription, amdPrompt) and system prompt. Read this before diagnosing a silent call or a missing keypad response. Voice is not validated against what the TTS provider owns. The keypad tool only arms when turnHandling.profile is "ivr" or AMD detects a machine mid-call.1 param▾

Get one agent and its complete editable configuration, including voice, turnHandling (profile, dtmfToolDescription, amdPrompt) and system prompt. Read this before diagnosing a silent call or a missing keypad response. Voice is not validated against what the TTS provider owns. The keypad tool only arms when turnHandling.profile is "ivr" or AMD detects a machine mid-call.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the Speko agent to retrieve, as returned by agents.create or agents.list.

spekomcp_agents_graph_get#Read the authored execution graph stored for one agent version. Omit `version` for the agent latest. Returns graph:null when the version has no graph yet (not an error). Read this before agents.graph.replace so an edit starts from the current graph, never a guess.2 params▾

Read the authored execution graph stored for one agent version. Omit `version` for the agent latest. Returns graph:null when the version has no graph yet (not an error). Read this before agents.graph.replace so an edit starts from the current graph, never a guess.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent whose execution graph to read.

versionintegeroptionalSpecific agent version number to read the graph from. Omit to read the graph stored for the agent's latest version.

spekomcp_agents_graph_replace#Publish an authored execution graph as a NEW agent version. A graph change is a change to the agent, so it cuts a version the same way a config change does: the live config is carried forward unchanged and only the graph differs, which is what makes agents.rollback able to restore a previous workflow. WHOLE-OBJECT REPLACE — the graph you send becomes the graph, so read agents.graph.get first and send the full modified object, never a partial patch. Marks the graph source as "authored", which permanently protects it from the seeder. Rejects with INVALID_GRAPH plus the exact per-field reasons when the graph fails structural validation, and with VERSION_CONFLICT when the version you edited from is no longer live — re-read and retry rather than forcing.3 params▾

Publish an authored execution graph as a NEW agent version. A graph change is a change to the agent, so it cuts a version the same way a config change does: the live config is carried forward unchanged and only the graph differs, which is what makes agents.rollback able to restore a previous workflow. WHOLE-OBJECT REPLACE — the graph you send becomes the graph, so read agents.graph.get first and send the full modified object, never a partial patch. Marks the graph source as "authored", which permanently protects it from the seeder. Rejects with INVALID_GRAPH plus the exact per-field reasons when the graph fails structural validation, and with VERSION_CONFLICT when the version you edited from is no longer live — re-read and retry rather than forcing.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent whose execution graph to replace.

graphobjectrequiredWhole-object replace: read agents.graph.get first, then send back the complete modified graph for this agent version — the value you send becomes the new graph, never a partial patch. A graph names one entryNodeId and lists the nodes and edges the call walks through. Each node has a unique id, a kind (entry, message, tool, logic_split, extract_variable, press_digit, code, mcp, subagent, sms, note, transfer, or end — the runtime currently walks entry, message, tool, note, transfer, and end; the rest are authorable and saved but not yet executed), a label, and kind-specific detail such as what the model should accomplish there, a verbatim line for an end node, state slots it can capture, or the tool/MCP server/subagent it calls. Edges connect node ids and branch on a condition: unconditional, an LLM judgment, a deterministic expression over captured slots, or whether a prior tool call succeeded or failed. globalEdges add caller-initiated jumps that work from any node; anything not represented there is dropped. Preserve each node's canvas position or the layout is redrawn. Example: {"entryNodeId": "start", "nodes": [{"id": "start", "kind": "entry", "label": "Start"}, {"id": "bye", "kind": "end", "label": "Goodbye", "say": "Thanks for calling, goodbye!"}], "edges": [{"id": "e1", "from": "start", "to": "bye", "condition": {"type": "unconditional"}}]}

versionintegerrequiredRequired. The version you EDITED FROM — the one agents.graph.get returned. Used as a concurrency token: if it is no longer the live version the write is refused rather than burying whoever published in between. The graph lands on a new version.

spekomcp_agents_graph_seed#Derive a first execution graph for an agent version from its system prompt (falling back to the version derived flow). Idempotent: an existing graph is returned unchanged with status "exists". `force` re-derives ONLY over a previously seeded graph — an authored or healed graph is never clobbered. Use this to bootstrap, then agents.graph.replace to edit.3 params▾

Derive a first execution graph for an agent version from its system prompt (falling back to the version derived flow). Idempotent: an existing graph is returned unchanged with status "exists". `force` re-derives ONLY over a previously seeded graph — an authored or healed graph is never clobbered. Use this to bootstrap, then agents.graph.replace to edit.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to derive a starter execution graph for.

forcebooleanrequiredWhether to re-derive the graph even if one already exists. Only applies to a previously auto-seeded graph (status "seeded"); an authored or healed graph is never overwritten regardless of this flag. Defaults to false, which returns the existing graph unchanged with status "exists" if one is already present.

versionintegeroptionalSpecific agent version number to seed a graph for. Omit to seed the agent's latest version.

spekomcp_agents_list#List agents in the current workspace without their full system prompts. Each item includes voice, turnHandling and runMode as currently stored. Use agents.get for one agent when the full system prompt is also needed.0 params▾

List agents in the current workspace without their full system prompts. Each item includes voice, turnHandling and runMode as currently stored. Use agents.get for one agent when the full system prompt is also needed.

spekomcp_agents_monitoring_results_list#List production calls scored by online monitoring (verdict + scores per call).1 param▾

List production calls scored by online monitoring (verdict + scores per call).

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent whose scored production calls to list, as returned by agents.create or agents.list.

spekomcp_agents_monitors_create#Create an alert monitor on an agent (fires when a metric crosses its threshold).2 params▾

Create an alert monitor on an agent (fires when a metric crosses its threshold).

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent to attach the alert monitor to, as returned by agents.create or agents.list.

bodyobjectrequiredJSON object describing the alert rule to create. Give it a name and pick the metric to watch (for example pass_rate, latency.p95_ms, or verdict), then say how to evaluate it: aggregation is usually 'single' — check the latest scored call as it comes in — or 'rolling_window' / 'on_run_complete' for a steadier signal over several calls. Combine a comparison operator (less-than, greater-than, equal, etc., inclusive or not) with a threshold: a numeric threshold for metrics like pass_rate or latency, or a string threshold when watching the 'verdict' metric. Optionally add a longer description, a window_size_runs count for rolling aggregations, and channels telling the monitor where to notify — Slack (a channel name or incoming webhook URL), email (a comma-separated recipient list), and/or a generic webhook (URL plus signing secret). Leaving channels empty still records breaches in the dashboard, it just won't page anyone. Example: {"name": "Pass rate drop", "metric_ref": "pass_rate", "aggregation": "single", "operator": "lt", "threshold_float": 0.8, "channels": {"slack": {"channel": "#alerts"}}}.

spekomcp_agents_monitors_delete#Delete an alert monitor.2 params▾

Delete an alert monitor.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent that owns the monitor, as returned by agents.create or agents.list.

monitor_idstringrequiredUnique identifier of the alert monitor to delete, as returned by agents.monitors.create or agents.monitors.list.

spekomcp_agents_monitors_events_list#List a monitor's firing history (breach events + observed values).2 params▾

List a monitor's firing history (breach events + observed values).

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent that owns the monitor, as returned by agents.create or agents.list.

monitor_idstringrequiredUnique identifier of the alert monitor whose firing history to list, as returned by agents.monitors.create or agents.monitors.list.

spekomcp_agents_monitors_list#List an agent's alert monitors — rules that watch an eval metric on scored production calls and notify when it crosses a threshold.1 param▾

List an agent's alert monitors — rules that watch an eval metric on scored production calls and notify when it crosses a threshold.

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent whose alert monitors to list, as returned by agents.create or agents.list.

spekomcp_agents_monitors_update#Update an alert monitor (threshold, channels, status, etc.).3 params▾

Update an alert monitor (threshold, channels, status, etc.).

NameTypeRequiredDescription

agent_idstringrequiredUnique identifier of the agent that owns the monitor, as returned by agents.create or agents.list.

bodyobjectrequiredJSON object with the fields to change on this monitor; every field is optional and only the ones you include are updated. You can rename it, edit its description, change which metric it watches or how it aggregates evaluations, swap the comparison operator or threshold (a numeric threshold_float, or threshold_string for the 'verdict' metric), adjust window_size_runs, replace its notification channels (Slack, email, webhook), or set status to 'active' or 'deleted' to pause or remove it without a separate delete call. Example: {"threshold_float": 0.75, "status": "active"}.

monitor_idstringrequiredUnique identifier of the alert monitor to update, as returned by agents.monitors.create or agents.monitors.list.

spekomcp_agents_preview_stacks#Preview the THREE voice-stack options before creating an agent — so the user picks. Returns the same recommendation the dashboard's agent-create shows, as three tiers. Present them to the user with these labels and each tier's STT / LLM / TTS: premium -> "Quality" balanced -> "Fastest" cost_optimized -> "Cheapest" Ask which one they want (and confirm the region — default USA). Then call create_agent with the chosen objective mapped to intent.optimizeFor: Quality -> 'quality', Fastest -> 'latency', Cheapest -> 'cost' plus intent.region. The server then pins that tier's failover stack automatically, so the created agent matches exactly what you previewed.2 params▾

Preview the THREE voice-stack options before creating an agent — so the user picks. Returns the same recommendation the dashboard's agent-create shows, as three tiers. Present them to the user with these labels and each tier's STT / LLM / TTS: premium -> "Quality" balanced -> "Fastest" cost_optimized -> "Cheapest" Ask which one they want (and confirm the region — default USA). Then call create_agent with the chosen objective mapped to intent.optimizeFor: Quality -> 'quality', Fastest -> 'latency', Cheapest -> 'cost' plus intent.region. The server then pins that tier's failover stack automatically, so the created agent matches exactly what you previewed.

NameTypeRequiredDescription

descriptionstringrequiredOne line on what the agent does, e.g. 'a dental clinic phone receptionist that books appointments'. Used to tailor the three stack recommendations to the use case.

regionstringoptionalRegion for latency-aware stack picks. Only 'usa' (United States) is supported today; defaults to 'usa'. More regions may be added later.

spekomcp_agents_rollback#Roll an agent back to a historical version.2 params▾

Roll an agent back to a historical version.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to roll back.

target_version_numberintegerrequiredThe historical version number to roll this agent back to — see List Agent Versions for the available numbers.

spekomcp_agents_test_call#Start an agent-to-agent test call. Dispatches the agent under test plus a caller (a persona synthesized from `objective`, or another agent via `caller_agent_id`) into ONE LiveKit room with NO phone/SIP leg — so it CANNOT hairpin the way dialing the agent's own number does. Returns immediately with session ids; the conversation runs in the background. To review it: poll calls.get(agentSessionId) until it ends, then read sessions.transcript.get(agentSessionId) and calls.recording.get(agentSessionId). Provide exactly one of objective / caller_agent_id / caller_system_prompt.7 params▾

Start an agent-to-agent test call. Dispatches the agent under test plus a caller (a persona synthesized from `objective`, or another agent via `caller_agent_id`) into ONE LiveKit room with NO phone/SIP leg — so it CANNOT hairpin the way dialing the agent's own number does. Returns immediately with session ids; the conversation runs in the background. To review it: poll calls.get(agentSessionId) until it ends, then read sessions.transcript.get(agentSessionId) and calls.recording.get(agentSessionId). Provide exactly one of objective / caller_agent_id / caller_system_prompt.

NameTypeRequiredDescription

agent_idstringrequiredAgent id to test (the agent under test). It answers first, using its saved config.

caller_agent_idstringoptionalUse another persisted agent as the caller instead of a synthesized persona.

caller_first_messagestringoptionalCaller's opening line. Defaults to listening first so the two agents don't greet over each other (only the agent under test greets).

caller_system_promptstringoptionalFull system prompt for the caller persona; overrides objective.

objectivestringoptionalPlain-language goal for a synthesized caller. Provide this, OR caller_agent_id, OR caller_system_prompt.

recordbooleanoptionalRecord the conversation. Default true (subject to org recording settings).

ttl_secondsintegeroptionalHard wall-clock cap in seconds (30-1800, default 180).

spekomcp_agents_tools_create#Register a new tool on an agent. A call already in progress will not see it; a new call will, once list_agent_tools shows it registered.2 params▾

Register a new tool on an agent. A call already in progress will not see it; a new call will, once list_agent_tools shows it registered.

NameTypeRequiredDescription

agent_idstringrequiredAgent id.

bodyobjectrequiredJSON body for POST /v1/agents/{agentId}/tools. Provide a name (an identifier the agent's model will call — letters, digits and underscores only, starting with a letter or underscore, up to 64 characters), a description explaining when and how to use it (1-1024 characters), and a parameters field containing a JSON Schema object describing the tool's arguments. source says how the tool is fulfilled: {kind: 'inline'} needs nothing further; {kind: 'webhook', url, secret, headers?, timeoutMs?, responseMode?, asyncAck?} posts to a URL you host, signed with a secret of at least 8 characters, with an optional timeoutMs (100-4000) and a responseMode of 'sync' or 'async'; {kind: 'builtin', name, config?} invokes one of Speko's built-in tools by name; {kind: 'integration', installationId, appKey, actionKey, config?} calls an installed integration action.

spekomcp_agents_tools_delete#Delete one agent tool. A call already in progress may keep using it until the call ends; new calls stop seeing it immediately.2 params▾

Delete one agent tool. A call already in progress may keep using it until the call ends; new calls stop seeing it immediately.

NameTypeRequiredDescription

agent_idstringrequiredId of the Speko agent that owns the tool.

tool_idstringrequiredId of the agent tool to delete.

spekomcp_agents_tools_get#Get one agent tool by id, as currently stored in the registry.2 params▾

Get one agent tool by id, as currently stored in the registry.

NameTypeRequiredDescription

agent_idstringrequiredId of the Speko agent that owns the tool.

tool_idstringrequiredId of the agent tool to fetch.

spekomcp_agents_tools_list#List tools registered on an agent, most recently created first. A call already in progress does not see a tool registered after it started. If a call reports an unknown tool, confirm it is listed here, then start a new call.1 param▾

List tools registered on an agent, most recently created first. A call already in progress does not see a tool registered after it started. If a call reports an unknown tool, confirm it is listed here, then start a new call.

NameTypeRequiredDescription

agent_idstringrequiredAgent id.

spekomcp_agents_tools_update#Update one agent tool's description, parameters, or source. A call already in progress keeps using the version it started with.3 params▾

Update one agent tool's description, parameters, or source. A call already in progress keeps using the version it started with.

NameTypeRequiredDescription

agent_idstringrequiredId of the Speko agent that owns the tool.

bodyobjectrequiredJSON object for PATCH /v1/agents/{agentId}/tools/{toolId}. All fields are optional: description (1-1024 characters), parameters (a JSON Schema object describing the tool's arguments), and source (the same shape accepted when creating the tool — for a webhook source, secret is optional on update; omit it to keep the existing secret). A call already in progress keeps using the version of the tool it started with. Example: {"description": "Looks up order status by order id."}

tool_idstringrequiredId of the agent tool to update.

spekomcp_agents_update#Update one Speko agent.2 params▾

Update one Speko agent.

NameTypeRequiredDescription

agent_idstringrequiredAgent id.

bodyobjectrequiredJSON body for PATCH /v1/agents/{id}. Only the fields you include are changed, and setting a nullable field to null clears it. Update the agent's name (<=120 chars), systemPrompt, or voice. intent controls call routing: language (BCP-47) plus an optional optimizeFor of 'latency', 'quality' or 'cost'. llmOptions tunes the model (temperature 0-2, maxTokens, or a model override). stackPreferences restricts which providers may be used per component (stt/llm/tts/s2s). sttOptions and ttsOptions configure speech recognition and synthesis — recognition keywords, diarization, expected speaker count, smart formatting, filler-word and profanity handling, and per-provider options for STT; playback speed, model, workload and provider options for TTS. runMode switches between a 'cascade' (separate STT/LLM/TTS) pipeline and a speech-to-speech 's2s' model. backgroundAudio sets an ambient sound and a sound that plays while a tool call is in flight. speechNormalization supplies a pronunciation dictionary and text replacements. turnHandling controls conversational behavior, including a 'profile' of 'ivr' that keeps the agent's keypad (DTMF) tool armed for the whole call instead of only when answering-machine detection flags a menu mid-call. webhooks registers callback URLs for call lifecycle events (preCall, postCall, status, analysis, recording), each as {url, headers?, timeoutMs?}.

spekomcp_agents_versions_list#List versions for an agent.1 param▾

List versions for an agent.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent whose versions to list.

spekomcp_api_keys_create#Create a product API key and return its secret in `key` exactly once; it is never retrievable again, so store it immediately. `scopes` is 1 to 6 values from speko:read, write, execute, billing, credentials, compliance, and the key can only do what those scopes allow. `routing_policy`, if set, pins this key to a specific stt/llm/tts provider chain and objective instead of the workspace default; omit it to inherit the default. Available to any workspace member, unlike other credential actions on this surface which require an admin.3 params▾

Create a product API key and return its secret in `key` exactly once; it is never retrievable again, so store it immediately. `scopes` is 1 to 6 values from speko:read, write, execute, billing, credentials, compliance, and the key can only do what those scopes allow. `routing_policy`, if set, pins this key to a specific stt/llm/tts provider chain and objective instead of the workspace default; omit it to inherit the default. Available to any workspace member, unlike other credential actions on this surface which require an admin.

NameTypeRequiredDescription

namestringrequiredDisplay name for the new API key, 1 to 100 characters. Used to tell keys apart in api_keys.list; it is not part of the key's authentication material.

scopesarrayrequired1 to 6 scopes granting this key permission to read, write, execute, access billing, manage credentials, or access compliance data. The key can only perform actions its scopes allow. Provide as an array of scope strings.

routing_policyobjectoptionalOptional routing policy that pins this key to a specific provider chain and objective instead of inheriting the workspace default. When provided it must include: language (BCP-47 string), useCase (one of realtime_agent, phone_agent, transcription, voice_content, translation, other, or null), objective (latency, cost, quality, or balanced), maxPricePerMinUsd (a ceiling in USD, or null for no ceiling), a deny list of disallowed provider ids, and per-stage stt/llm/tts objects each with a provider chain plus optional voice, instructions, gender, a pinned model+voice pair, and provider-specific string overrides. Omit this entire field to use the workspace's default routing.

spekomcp_api_keys_list#List product API keys in the current workspace, each with its scopes, revocation state, and resourceVersion. resourceVersion is literally "active" or "revoked", not an incrementing version, so it stays valid for api_keys.revoke as long as the key remains active; there is no need to re-read it immediately before revoking.0 params▾

List product API keys in the current workspace, each with its scopes, revocation state, and resourceVersion. resourceVersion is literally "active" or "revoked", not an incrementing version, so it stays valid for api_keys.revoke as long as the key remains active; there is no need to re-read it immediately before revoking.

spekomcp_api_keys_revoke#Revoke one product API key. `expected_resource_version` must be "active", the only value an unrevoked key ever has; it does not need a fresh read from api_keys.list first, since the value cannot go stale while the key stays active. Concurrent revokes are safe: only one succeeds, the other is refused. Revocation cannot be undone.2 params▾

Revoke one product API key. `expected_resource_version` must be "active", the only value an unrevoked key ever has; it does not need a fresh read from api_keys.list first, since the value cannot go stale while the key stays active. Concurrent revokes are safe: only one succeeds, the other is refused. Revocation cannot be undone.

NameTypeRequiredDescription

api_key_idstringrequiredThe id of the product API key to revoke, as a UUID. Get it from Api Keys List.

expected_resource_versionstringrequiredConcurrency token that must equal the key's current resourceVersion, which is literally "active" for any unrevoked key. Pass "active" unless api_keys.list ever reports a different value for this key. Between 1 and 200 characters.

spekomcp_audio_synthesize#Synthesize speech from text, returning base64 audio. Routed across TTS providers by the intent. The audio is returned as base64 with its content type and sample rate so a client can save or play it. Served by the Speko Router when the request is one the Router's speech body can express, and by the Platform endpoint otherwise — a request naming `speed`, `instructions`, `spokenForm`, a bare `model` or more than one allowed provider keeps the knob it asked for rather than losing it.1 param▾

Synthesize speech from text, returning base64 audio. Routed across TTS providers by the intent. The audio is returned as base64 with its content type and sample rate so a client can save or play it. Served by the Speko Router when the request is one the Router's speech body can express, and by the Platform endpoint otherwise — a request naming `speed`, `instructions`, `spokenForm`, a bare `model` or more than one allowed provider keeps the knob it asked for rather than losing it.

NameTypeRequiredDescription

bodyobjectrequiredJSON body for the speech-synthesis request sent to POST /v1/synthesize. Provide the text to speak (1-50000 characters, must contain at least one speakable character) and an intent object with a BCP-47 language tag (region and optimizeFor are optional, optimizeFor being 'balanced', 'accuracy', 'latency', or 'cost'). Optional fields let you pin a specific voice or upstream model (such as 'eleven_multilingual_v2' or 'sonic-2'), adjust playback speed (0.5-2), give speaking-style instructions (used only when the resolved model supports them), turn on spokenForm to normalize markdown, URLs and numbers before synthesis, choose an output sample rate (16000, 24000, 44100, or 48000 Hz), and restrict which TTS providers may be used via constraints.allowedProviders.tts. Example: {"text": "Thanks for calling, how can I help?", "intent": {"language": "en"}, "voice": "warm-female-1", "speed": 1.1}

spekomcp_audio_transcribe#Transcribe audio to text. Speech to text only: no audio is generated and none is returned. Google Drive's "can't scan for viruses" confirmation pages are refused as web pages; use a link that downloads the audio without a confirmation form.4 params▾

Transcribe audio to text. Speech to text only: no audio is generated and none is returned. Google Drive's "can't scan for viruses" confirmation pages are refused as web pages; use a link that downloads the audio without a confirmation form.

NameTypeRequiredDescription

audio_urlstringrequiredHTTPS URL of the audio file (mp3, wav, m4a, ogg, flac, webm; up to 25 MB) that downloads without a sign-in. Google Drive and Dropbox share links to a FILE are accepted and converted to direct downloads; in Drive the file must be shared as 'Anyone with the link'. Signed recording URLs from sessions.recording.get and calls.recording.get work directly.

keywordsarrayoptionalDomain-specific terms to bias speech recognition toward, up to 200 entries. Omit if not needed.

languagestringoptionalBCP-47 language tag such as 'en' or 'es-MX'. Defaults to 'en' when omitted.

word_timestampsbooleanoptionalReturn per-word start/end timings alongside the transcript, for subtitles and alignment. Adds a `words` array of {text, start_ms, end_ms}. Defaults to false.

spekomcp_billing_auto_topup_get#Get the current automatic credit top-up configuration and payment-method status. hasPaymentMethod and the nested paymentMethod fields cover the card Stripe has on file, separate from whether auto-top-up is enabled. A nonzero failureCount with pausedAt and lastFailureReason set means a top-up attempt failed and charging is paused. Call billing.auto_topup.resume to clear that once the underlying issue is fixed, or billing.auto_topup.update to reconfigure a new threshold or amount.0 params▾

Get the current automatic credit top-up configuration and payment-method status. hasPaymentMethod and the nested paymentMethod fields cover the card Stripe has on file, separate from whether auto-top-up is enabled. A nonzero failureCount with pausedAt and lastFailureReason set means a top-up attempt failed and charging is paused. Call billing.auto_topup.resume to clear that once the underlying issue is fixed, or billing.auto_topup.update to reconfigure a new threshold or amount.

spekomcp_billing_auto_topup_resume#Clear a paused auto-top-up failure state so charging may resume, without changing the threshold or amount on file. Check billing.auto_topup.get first to confirm pausedAt is actually set; calling this when auto-top-up was never paused is a no-op. Requires a human OAuth principal, not an API key.0 params▾

Clear a paused auto-top-up failure state so charging may resume, without changing the threshold or amount on file. Check billing.auto_topup.get first to confirm pausedAt is actually set; calling this when auto-top-up was never paused is a no-op. Requires a human OAuth principal, not an API key.

spekomcp_billing_auto_topup_setup#Create a short-lived Stripe handoff for authorizing an auto-top-up card. Returns a url, its purpose, and an expiresAt timestamp; completing it on Stripe attaches a payment method without itself enabling auto-top-up. Call billing.auto_topup.update afterward with enabled true plus a threshold and amount to turn charging on. Requires a human OAuth principal, not an API key.0 params▾

Create a short-lived Stripe handoff for authorizing an auto-top-up card. Returns a url, its purpose, and an expiresAt timestamp; completing it on Stripe attaches a payment method without itself enabling auto-top-up. Call billing.auto_topup.update afterward with enabled true plus a threshold and amount to turn charging on. Requires a human OAuth principal, not an API key.

spekomcp_billing_auto_topup_update#Replace the automatic credit top-up configuration for the workspace. This is a whole-object replace, not a patch. enabled, thresholdCents, and amountCents must all be sent together even to change only one of them, and thresholdCents must be strictly less than amountCents or the call is rejected. Requires a human OAuth principal, not an API key.3 params▾

Replace the automatic credit top-up configuration for the workspace. This is a whole-object replace, not a patch. enabled, thresholdCents, and amountCents must all be sent together even to change only one of them, and thresholdCents must be strictly less than amountCents or the call is rejected. Requires a human OAuth principal, not an API key.

NameTypeRequiredDescription

amountCentsintegerrequiredAmount, in cents, to charge the card on file each time an automatic top-up fires. From 500 to 1,000,000, and must be strictly greater than thresholdCents.

enabledbooleanrequiredWhether automatic top-up should be turned on. Must be sent together with thresholdCents and amountCents even when only one of the three values is actually changing.

thresholdCentsintegerrequiredCredit balance threshold, in cents, that triggers an automatic top-up once the balance drops to or below it. Must be greater than 0, up to 1,000,000, and strictly less than amountCents.

spekomcp_billing_checkout_create#Create a short-lived Stripe Checkout handoff for adding workspace credits. Returns a url, its purpose, and an expiresAt timestamp; the caller opens the url to complete payment, this action does not itself move any money. amount_usd is a whole dollar figure between 5 and 10,000. Requires a human OAuth principal, not an API key.1 param▾

Create a short-lived Stripe Checkout handoff for adding workspace credits. Returns a url, its purpose, and an expiresAt timestamp; the caller opens the url to complete payment, this action does not itself move any money. amount_usd is a whole dollar figure between 5 and 10,000. Requires a human OAuth principal, not an API key.

NameTypeRequiredDescription

amount_usdintegerrequiredWhole-dollar amount of workspace credits to purchase via Stripe Checkout, between 5 and 10,000 USD.

spekomcp_billing_invoices_list#List recent Stripe invoices for the current workspace, newest first. limit caps the page size at 100 and defaults to 25. Each invoice reports amountPaid and amountDue in the smallest currency unit, plus nullable hostedInvoiceUrl and invoicePdf links once Stripe has generated them.1 param▾

List recent Stripe invoices for the current workspace, newest first. limit caps the page size at 100 and defaults to 25. Each invoice reports amountPaid and amountDue in the smallest currency unit, plus nullable hostedInvoiceUrl and invoicePdf links once Stripe has generated them.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of invoices to return in this page, from 1 to 100. Defaults to 25 when omitted.

spekomcp_billing_portal_create#Create a short-lived Stripe Billing Portal handoff for the workspace. Returns a url, its purpose, and an expiresAt timestamp; the portal itself lets the account owner manage payment methods and view invoices on Stripe. Requires a human OAuth principal, not an API key.0 params▾

Create a short-lived Stripe Billing Portal handoff for the workspace. Returns a url, its purpose, and an expiresAt timestamp; the portal itself lets the account owner manage payment methods and view invoices on Stripe. Requires a human OAuth principal, not an API key.

spekomcp_calls_get#Get call detail including transcript.1 param▾

Get call detail including transcript.

NameTypeRequiredDescription

call_idstringrequiredUnique identifier of the call (also usable as a session id) to retrieve full details and transcript for.

spekomcp_calls_recording_get#Get a signed recording URL for one call.1 param▾

Get a signed recording URL for one call.

NameTypeRequiredDescription

call_idstringrequiredUnique identifier of the call to get a signed, time-limited recording URL for.

spekomcp_capabilities_describe#Return the exact input schema, output schema and authorization policy for one action, by id. The natural second call after capabilities.search, when a summary is not enough to construct the arguments.1 param▾

Return the exact input schema, output schema and authorization policy for one action, by id. The natural second call after capabilities.search, when a summary is not enough to construct the arguments.

NameTypeRequiredDescription

actionIdstringrequiredId of the action to describe, as returned in a capabilities.search result (3-200 characters).

spekomcp_capabilities_search#Search the actions available to the current principal and MCP profile. An empty query (the default) returns everything visible, up to limit. Filter by effect to find only "read", "write", "destructive" and so on. Each result is a summary; pass its id to capabilities.describe for the full input and output schema.3 params▾

Search the actions available to the current principal and MCP profile. An empty query (the default) returns everything visible, up to limit. Filter by effect to find only "read", "write", "destructive" and so on. Each result is a summary; pass its id to capabilities.describe for the full input and output schema.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of matching actions to return, from 1 to 100. Defaults to 25 when omitted.

querystringrequiredFree-text search query matched against action names and descriptions. Leave blank (the default) to list every action visible to your current principal and profile, up to Limit.

effectstringoptionalRestrict results to actions with this effect classification. Omit to include actions of every effect type.

spekomcp_code_snippets_get#Get ready-to-paste Speko integration code for a web voice call. Returns correct, compilable code for the canonical Speko runtime flow: the app's server mints a session via POST /v1/sessions with the secret SPEKO_API_KEY, then the browser connects with @spekoai/client's VoiceConversation.create using the returned short-lived transportToken and transportUrl. Use this INSTEAD of guessing Speko API shapes when generating app code. Note: generated apps cannot call MCP tools at runtime - runtime integration is exactly this code plus a SPEKO_API_KEY environment variable.1 param▾

Get ready-to-paste Speko integration code for a web voice call. Returns correct, compilable code for the canonical Speko runtime flow: the app's server mints a session via POST /v1/sessions with the secret SPEKO_API_KEY, then the browser connects with @spekoai/client's VoiceConversation.create using the returned short-lived transportToken and transportUrl. Use this INSTEAD of guessing Speko API shapes when generating app code. Note: generated apps cannot call MCP tools at runtime - runtime integration is exactly this code plus a SPEKO_API_KEY environment variable.

NameTypeRequiredDescription

frameworkstringrequiredTarget framework for the integration snippet: 'nextjs' (App Router route handler + client page), 'react' (browser component for any SPA), 'node' (Express session-mint endpoint), 'python' (FastAPI session-mint endpoint), or 'curl' (raw HTTP).

spekomcp_credits_balance_get#Get the current workspace prepaid credit balance in USD, as of updatedAt. Requires the speko:billing scope, unlike most reads on this surface.0 params▾

Get the current workspace prepaid credit balance in USD, as of updatedAt. Requires the speko:billing scope, unlike most reads on this surface.

spekomcp_credits_ledger_list#List recent credit movements for the current workspace, newest first. Filter with kind as a comma-separated list of "grant", "debit", "topup", "refund" and "adjustment". Page with the returned nextCursor; it is null on the last page. provider, sessionId and stripePaymentIntentId are populated only on the entry kinds that produced them.3 params▾

List recent credit movements for the current workspace, newest first. Filter with kind as a comma-separated list of "grant", "debit", "topup", "refund" and "adjustment". Page with the returned nextCursor; it is null on the last page. provider, sessionId and stripePaymentIntentId are populated only on the entry kinds that produced them.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of ledger entries to return in this page, from 1 to 200. Defaults to 50 when omitted.

cursorstringoptionalPagination cursor: pass the nextCursor timestamp returned by a previous call to fetch the next page of ledger entries. Omit to start from the most recent entry.

kindstringoptionalComma-separated list of ledger entry kinds to include: grant, debit, topup, refund, adjustment. Omit to return all kinds.

spekomcp_docs_search#Search bundled Speko docs. Returns slug, title, score, snippet. Use this to look up SDK usage, API request/body shapes, and migration steps without leaving the MCP session. For example, after a Speko API validation error, search the failing field name to find the correct shape. Each hit's `slug` can be opened as the `spekoai://docs/{slug}` resource; `spekoai://docs/index` lists every bundled doc.2 params▾

Search bundled Speko docs. Returns slug, title, score, snippet. Use this to look up SDK usage, API request/body shapes, and migration steps without leaving the MCP session. For example, after a Speko API validation error, search the failing field name to find the correct shape. Each hit's `slug` can be opened as the `spekoai://docs/{slug}` resource; `spekoai://docs/index` lists every bundled doc.

NameTypeRequiredDescription

querystringrequiredFree-text query. Matched case-insensitively against the titles and bodies of every bundled Speko doc (hosted llms.txt exports, SDK/adapter READMEs, migration guides, quickstart).

limitintegeroptionalMax hits to return, from 1 to 20. Defaults to 5.

spekomcp_evals_get#Get eval detail and recent runs.1 param▾

Get eval detail and recent runs.

NameTypeRequiredDescription

eval_idstringrequiredUnique identifier of the eval to retrieve, as returned by agents.evals.create or agents.evals.list.

spekomcp_gateway_activity_list#List recent Gateway activity events for the current workspace, newest first, optionally filtered to one workload, one instance, or one event_type. Each row carries the provider and session/attempt ids. `attribution`, when present, names which client made the request under a fixed evidence classification. A malformed attribution on an otherwise-valid event silently drops to undefined rather than failing the row, so an absent attribution does not mean the event is invalid.4 params▾

List recent Gateway activity events for the current workspace, newest first, optionally filtered to one workload, one instance, or one event_type. Each row carries the provider and session/attempt ids. `attribution`, when present, names which client made the request under a fixed evidence classification. A malformed attribution on an otherwise-valid event silently drops to undefined rather than failing the row, so an absent attribution does not mean the event is invalid.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of activity events to return, from 1 to 200. Defaults to 50 when omitted.

event_typestringoptionalOptional event type to filter to a single kind of Gateway activity event, such as "session_started" or "session_error". Up to 128 characters. Omit to include all event types.

instance_idstringoptionalOptional Gateway runtime instance id to filter events to a single instance. Get it from gateway.instances.list. Up to 256 characters. Omit to include events from all instances.

workload_idstringoptionalOptional workload id to filter events to a single Gateway workload. Get it from gateway.workloads.list. Up to 256 characters. Omit to include events from all workloads.

spekomcp_gateway_instances_list#List Gateway runtime instances in the current workspace, each with its active and pending session counts, capacity, and whether it is online, draining, or already offline. `draining: true` means the instance is finishing its current sessions and refusing new ones ahead of a planned shutdown. `offlineAt` is null while online and set once it drops off.0 params▾

List Gateway runtime instances in the current workspace, each with its active and pending session counts, capacity, and whether it is online, draining, or already offline. `draining: true` means the instance is finishing its current sessions and refusing new ones ahead of a planned shutdown. `offlineAt` is null while online and set once it drops off.

spekomcp_gateway_legacy_keys_list#List legacy Runtime API keys still valid during the migration window, each with its expiry, revocation state, and resourceVersion. `legacyAcceptUntil`, when present, is the workspace-level deprecation cutoff date for these keys, set by the Runtime service rather than this action. gateway.legacy_keys.revoke needs the resourceVersion from this list as a concurrency token.0 params▾

List legacy Runtime API keys still valid during the migration window, each with its expiry, revocation state, and resourceVersion. `legacyAcceptUntil`, when present, is the workspace-level deprecation cutoff date for these keys, set by the Runtime service rather than this action. gateway.legacy_keys.revoke needs the resourceVersion from this list as a concurrency token.

spekomcp_gateway_legacy_keys_revoke#Revoke one legacy Runtime API key. `expected_resource_version` must match the key's current resourceVersion from gateway.legacy_keys.list; a stale value is refused rather than revoking blind, so read the key immediately before revoking. Revocation cannot be undone.2 params▾

Revoke one legacy Runtime API key. `expected_resource_version` must match the key's current resourceVersion from gateway.legacy_keys.list; a stale value is refused rather than revoking blind, so read the key immediately before revoking. Revocation cannot be undone.

NameTypeRequiredDescription

expected_resource_versionstringrequiredConcurrency token that must match the key's current resourceVersion as returned by gateway.legacy_keys.list. A stale value is refused rather than revoking blind, so re-read the key immediately before calling this. Between 1 and 200 characters.

key_idstringrequiredThe id of the legacy Runtime API key to revoke. Get it from gateway.legacy_keys.list. Between 1 and 256 characters.

spekomcp_gateway_models_list#List Relay models with their provider, kind (stt, tts, llm, or s2s), routability, and benchmark and ranking data for the given objective and language. Filtering by `language` narrows to models that actually serve it; omit both filters to see the full catalog and every language it covers. gateway.relay.tts_preview.create and other Relay-routed actions expect a (provider, model, voice) combination taken from this list, not guessed.2 params▾

List Relay models with their provider, kind (stt, tts, llm, or s2s), routability, and benchmark and ranking data for the given objective and language. Filtering by `language` narrows to models that actually serve it; omit both filters to see the full catalog and every language it covers. gateway.relay.tts_preview.create and other Relay-routed actions expect a (provider, model, voice) combination taken from this list, not guessed.

NameTypeRequiredDescription

languagestringoptionalOptional language code to narrow results to models that actually serve it. Between 1 and 32 characters. Omit both filters to see every model and every language it covers.

objectivestringoptionalOptional ranking objective to filter or sort models by: balanced, quality, latency, or cost. Omit to see the full catalog without objective-based ranking.

spekomcp_gateway_overview_get#Get one snapshot of the current workspace Gateway: session counts (total, last 24h, active), 24h error count, active key count, workload and instance counts, and settled spend in micros. Each figure has its own detail action when the summary number is not enough: gateway.workloads.list, gateway.instances.list, gateway.activity.list, gateway.usage.get.0 params▾

Get one snapshot of the current workspace Gateway: session counts (total, last 24h, active), 24h error count, active key count, workload and instance counts, and settled spend in micros. Each figure has its own detail action when the summary number is not enough: gateway.workloads.list, gateway.instances.list, gateway.activity.list, gateway.usage.get.

spekomcp_gateway_profiler_conversations_get#Get one profiler conversation with every turn assembled: latency breakdown (ear-to-mouth, endpointing, LLM time to first token, tool time, TTS time to first audio), barge-in and overspeech timing, and a `confidence` of complete, degraded, or minimal reflecting how many of the expected markers actually arrived. `violations` and `missing_markers` name specifics when confidence is not complete. gateway.profiler.turn_trace.get returns the raw event trace behind one turn when this summary is not enough.1 param▾

Get one profiler conversation with every turn assembled: latency breakdown (ear-to-mouth, endpointing, LLM time to first token, tool time, TTS time to first audio), barge-in and overspeech timing, and a `confidence` of complete, degraded, or minimal reflecting how many of the expected markers actually arrived. `violations` and `missing_markers` name specifics when confidence is not complete. gateway.profiler.turn_trace.get returns the raw event trace behind one turn when this summary is not enough.

NameTypeRequiredDescription

conversation_idstringrequiredThe id of the profiler conversation to retrieve, from gateway.profiler.conversations.list. Between 1 and 256 characters.

spekomcp_gateway_profiler_conversations_list#List recent Gateway profiler conversations, each with its turn counts (total, evaluated, good) and good_turn_rate when evaluation has run, plus how it ended: hangup, transfer, error, shutdown, or unknown. gateway.profiler.conversations.get returns one conversation's full turn-by-turn detail; gateway.profiler.turn_trace.get goes one level deeper into a single turn.2 params▾

List recent Gateway profiler conversations, each with its turn counts (total, evaluated, good) and good_turn_rate when evaluation has run, plus how it ended: hangup, transfer, error, shutdown, or unknown. gateway.profiler.conversations.get returns one conversation's full turn-by-turn detail; gateway.profiler.turn_trace.get goes one level deeper into a single turn.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of profiler conversations to return, from 1 to 200. Defaults to 50 when omitted.

workload_idstringoptionalOptional workload id to filter conversations to a single workload. Get it from gateway.workloads.list. Up to 256 characters. Omit to include conversations from all workloads.

spekomcp_gateway_profiler_turn_trace_get#Get the raw, ordered event trace behind one profiler turn: every marker event with its type, sequence number, and millisecond timestamp, alongside the same turn summary gateway.profiler.conversations.get already returns. Use this when a turn's `confidence` is degraded or minimal and the summary alone does not explain which marker was missing or out of order.2 params▾

Get the raw, ordered event trace behind one profiler turn: every marker event with its type, sequence number, and millisecond timestamp, alongside the same turn summary gateway.profiler.conversations.get already returns. Use this when a turn's `confidence` is degraded or minimal and the summary alone does not explain which marker was missing or out of order.

NameTypeRequiredDescription

conversation_idstringrequiredThe id of the profiler conversation the turn belongs to, from gateway.profiler.conversations.list. Between 1 and 256 characters.

turn_idstringrequiredThe id of the specific turn within the conversation to trace, from gateway.profiler.conversations.get. Between 1 and 256 characters.

spekomcp_gateway_provider_credentials_delete#Delete a Relay provider credential. `expected_resource_version` must match the current resource_version from gateway.provider_credentials.list; a stale value is refused rather than deleting blind, so read the credential immediately before deleting rather than reusing an earlier version.2 params▾

Delete a Relay provider credential. `expected_resource_version` must match the current resource_version from gateway.provider_credentials.list; a stale value is refused rather than deleting blind, so read the credential immediately before deleting rather than reusing an earlier version.

NameTypeRequiredDescription

expected_resource_versionstringrequiredConcurrency token that must match this credential's current resource_version from gateway.provider_credentials.list. A stale value is refused rather than deleting blind, so read the credential immediately before deleting.

providerstringrequiredName of the Relay provider whose credential should be deleted, such as "openai" or "elevenlabs". Between 1 and 100 characters.

spekomcp_gateway_provider_credentials_list#List Relay provider credentials for the current workspace without exposing stored key values; only the last four characters, if configured, are shown. `resource_version`, present when configured, is the concurrency token gateway.provider_credentials.replace and .delete require.0 params▾

List Relay provider credentials for the current workspace without exposing stored key values; only the last four characters, if configured, are shown. `resource_version`, present when configured, is the concurrency token gateway.provider_credentials.replace and .delete require.

spekomcp_gateway_provider_credentials_replace#Create a Relay provider credential, or replace the existing one for that provider. `expected_resource_version` defaults to null, meaning no credential is expected to exist yet; set it to the current resource_version from gateway.provider_credentials.list to replace one that does, and the request is refused if the stored value has moved on since. The submitted `api_key` is never echoed back; only its last four characters appear afterward in gateway.provider_credentials.list.3 params▾

Create a Relay provider credential, or replace the existing one for that provider. `expected_resource_version` defaults to null, meaning no credential is expected to exist yet; set it to the current resource_version from gateway.provider_credentials.list to replace one that does, and the request is refused if the stored value has moved on since. The submitted `api_key` is never echoed back; only its last four characters appear afterward in gateway.provider_credentials.list.

NameTypeRequiredDescription

api_keystringrequiredThe provider's API key to store. Between 1 and 4096 characters. Never echoed back in full; only its last four characters appear afterward in gateway.provider_credentials.list.

expected_resource_versionstringrequiredConcurrency token guarding the write. Leave as null when no credential exists yet for this provider. To replace an existing credential, pass its current resource_version from gateway.provider_credentials.list; if the stored value has since moved on, the request is refused rather than overwriting blind.

providerstringrequiredName of the Relay provider the credential belongs to, such as "openai" or "elevenlabs". Between 1 and 100 characters.

spekomcp_gateway_relay_activity_list#List recent Relay requests, newest first, each with its full attempt chain: every provider tried, in order, with an outcome of served, failed, or superseded. `superseded` marks an attempt that a later, faster attempt beat rather than one that errored, so counting it as a failure overstates the failover rate. `routing_mode` is auto when Relay chose the chain and explicit when the caller pinned it.1 param▾

List recent Relay requests, newest first, each with its full attempt chain: every provider tried, in order, with an outcome of served, failed, or superseded. `superseded` marks an attempt that a later, faster attempt beat rather than one that errored, so counting it as a failure overstates the failover rate. `routing_mode` is auto when Relay chose the chain and explicit when the caller pinned it.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of Relay requests to return, from 1 to 200. Defaults to 50 when omitted.

spekomcp_gateway_relay_credit_get#Get the Runtime credit snapshot Relay uses to admit new requests: available balance in micros, open reserved micros not yet settled, and unexported settled micros not yet reflected in the platform balance. `source` is "platform" when the balance comes from the platform ledger and "runtime_default" when Runtime is using its own fallback figure instead.0 params▾

Get the Runtime credit snapshot Relay uses to admit new requests: available balance in micros, open reserved micros not yet settled, and unexported settled micros not yet reflected in the platform balance. `source` is "platform" when the balance comes from the platform ledger and "runtime_default" when Runtime is using its own fallback figure instead.

spekomcp_gateway_relay_tts_preview_create#Create a bounded Relay TTS preview and return a short-lived audio resource link. The voice id is not cross-checked against the chosen provider before synthesis. An id that belongs to a different vendor (for example an OpenAI voice name passed with provider: "azure") can be accepted and still fail or return silence instead of erroring up front. See gateway.models.list for a language's available provider and model pairs; prefer a voice already listed under the chosen provider.5 params▾

Create a bounded Relay TTS preview and return a short-lived audio resource link. The voice id is not cross-checked against the chosen provider before synthesis. An id that belongs to a different vendor (for example an OpenAI voice name passed with provider: "azure") can be accepted and still fail or return silence instead of erroring up front. See gateway.models.list for a language's available provider and model pairs; prefer a voice already listed under the chosen provider.

NameTypeRequiredDescription

languagestringrequiredLanguage code the preview text is in, such as "en-US". Between 1 and 32 characters. Use gateway.models.list to see which providers and models serve this language.

modestringrequiredSynthesis mode: "conversation" for conversational speech pacing, or "narration" for narrated/read-aloud pacing. Defaults to "conversation" when omitted.

modelstringrequiredThe TTS model id to use, taken from a (provider, model, voice) combination in gateway.models.list. Between 1 and 200 characters.

providerstringrequiredThe TTS provider to synthesize with, such as "elevenlabs" or "azure". Between 1 and 100 characters. Get valid providers for a language from gateway.models.list.

voicestringrequiredThe voice id to synthesize with. Between 1 and 300 characters. Not cross-checked against the chosen provider: a voice id from a different vendor can be accepted here and still fail or return silence instead of erroring up front. Prefer a voice already listed under the chosen provider in gateway.models.list.

spekomcp_gateway_relay_usage_get#Get Relay usage summed over a bounded recent window (1 to 2160 hours, default 168, one week), with total requests, failures, and failovers, the same three broken out as a time series, and again split by kind and by model. Failures and failovers are reported as separate counters, not combined into one rate.1 param▾

Get Relay usage summed over a bounded recent window (1 to 2160 hours, default 168, one week), with total requests, failures, and failovers, the same three broken out as a time series, and again split by kind and by model. Failures and failovers are reported as separate counters, not combined into one rate.

NameTypeRequiredDescription

window_hoursintegerrequiredSize of the recent window to sum Relay usage over, in hours, from 1 to 2160. Defaults to 168 (one week) when omitted.

spekomcp_gateway_usage_get#Get aggregated Gateway usage for the current workspace, broken down by provider: spend in micros of the given currency, session count, and the metering source behind the number when more than one exists.0 params▾

Get aggregated Gateway usage for the current workspace, broken down by provider: spend in micros of the given currency, session count, and the metering source behind the number when more than one exists.

spekomcp_gateway_workloads_list#List Gateway workloads in the current workspace, each identified by type and id, with its total and active session counts and when it was last seen.0 params▾

List Gateway workloads in the current workspace, each identified by type and id, with its total and active session counts and when it was last seen.

spekomcp_knowledge_bases_create#Create a knowledge base.1 param▾

Create a knowledge base.

NameTypeRequiredDescription

bodyobjectrequiredJSON body for POST /v1/knowledge-bases. Required shape: {agentId: string, name: string (1-120 chars)}. Optional: description (string <=2000).

spekomcp_knowledge_bases_delete#Delete one knowledge base.1 param▾

Delete one knowledge base.

NameTypeRequiredDescription

knowledge_base_idstringrequiredKnowledge-base id.

spekomcp_knowledge_bases_documents_create#Create a knowledge document row and upload URL.2 params▾

Create a knowledge document row and upload URL.

NameTypeRequiredDescription

bodyobjectrequiredJSON body for POST /v1/knowledge-bases/{kbId}/documents. Required shape: {filename: string (1-512 chars), contentType: MIME string such as 'text/markdown' (<=120 chars), sizeBytes: non-negative int}. Optional: metadata (object). The response includes an upload URL that accepts the file bytes by PUT. The document becomes searchable once finalize_knowledge_document records the upload.

knowledge_base_idstringrequiredKnowledge-base id.

spekomcp_knowledge_bases_documents_delete#Delete one knowledge document.2 params▾

Delete one knowledge document.

NameTypeRequiredDescription

document_idstringrequiredKnowledge-document id.

knowledge_base_idstringrequiredKnowledge-base id.

spekomcp_knowledge_bases_documents_finalize#Finalize a knowledge document and enqueue ingestion.2 params▾

Finalize a knowledge document and enqueue ingestion.

NameTypeRequiredDescription

document_idstringrequiredKnowledge-document id.

knowledge_base_idstringrequiredKnowledge-base id.

spekomcp_knowledge_bases_documents_get#Get one document from a workspace knowledge base. status is one of "pending", "processing", "ready" or "failed"; errorMessage is set on "failed" and ingestedAt stays null until the document reaches "ready". Use knowledge_bases.documents.list to find a document id first.2 params▾

Get one document from a workspace knowledge base. status is one of "pending", "processing", "ready" or "failed"; errorMessage is set on "failed" and ingestedAt stays null until the document reaches "ready". Use knowledge_bases.documents.list to find a document id first.

NameTypeRequiredDescription

document_idstringrequiredUnique identifier of the document to retrieve, as returned by knowledge_bases.documents.list or knowledge_bases.documents.create.

knowledge_base_idstringrequiredUnique identifier of the knowledge base the document belongs to.

spekomcp_knowledge_bases_documents_list#List documents in a workspace knowledge base, each with an ingestion status of "pending", "processing", "ready" or "failed", and its own chunkCount. Use knowledge_bases.documents.get on a "failed" entry to read its errorMessage.1 param▾

List documents in a workspace knowledge base, each with an ingestion status of "pending", "processing", "ready" or "failed", and its own chunkCount. Use knowledge_bases.documents.get on a "failed" entry to read its errorMessage.

NameTypeRequiredDescription

knowledge_base_idstringrequiredUnique identifier of the knowledge base whose documents to list, as returned by knowledge_bases.list or knowledge_bases.create.

spekomcp_knowledge_bases_get#Get one knowledge base owned by the current workspace, including its embeddingModel and current documentCount and chunkCount. Use knowledge_bases.list to find a base id first.1 param▾

Get one knowledge base owned by the current workspace, including its embeddingModel and current documentCount and chunkCount. Use knowledge_bases.list to find a base id first.

NameTypeRequiredDescription

knowledge_base_idstringrequiredUnique identifier of the knowledge base to retrieve, as returned by knowledge_bases.list or knowledge_bases.create.

spekomcp_knowledge_bases_list#List visible knowledge bases, optionally filtered to one agent with agent_id. Each entry carries documentCount and chunkCount as current totals, not a snapshot from creation. Use knowledge_bases.documents.list on a specific base to see why those counts are what they are.1 param▾

List visible knowledge bases, optionally filtered to one agent with agent_id. Each entry carries documentCount and chunkCount as current totals, not a snapshot from creation. Use knowledge_bases.documents.list on a specific base to see why those counts are what they are.

NameTypeRequiredDescription

agent_idstringoptionalOptional agent id to filter knowledge bases to just those belonging to one agent. Omit to list all knowledge bases visible to the workspace.

spekomcp_migration_briefing_render#Render briefing markdown for an agent/version.3 params▾

Render briefing markdown for an agent/version.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent whose migration briefing markdown should be rendered.

template_idstringoptionalId of the briefing template to render with. Defaults to 'web-in-app' when omitted.

version_idstringoptionalId of a specific AgentVersion to render the briefing for. Omit to render the briefing for the agent's current configuration.

spekomcp_migration_external_config_parse#Parse an external voice-agent config into a Speko SessionConfig draft. Output is a scaffold: verify it against the raw config and check `warnings` and `unmappable_tools` before creating anything.2 params▾

Parse an external voice-agent config into a Speko SessionConfig draft. Output is a scaffold: verify it against the raw config and check `warnings` and `unmappable_tools` before creating anything.

NameTypeRequiredDescription

formatstringrequiredThe external voice-agent platform this config was exported from. Determines how the raw text is parsed into a Speko SessionConfig draft.

rawstringrequiredThe external agent's configuration, exactly as exported from the source platform — typically JSON, though some platforms export YAML or another text format. This is what gets parsed into a Speko SessionConfig draft; check the response's warnings and unmappable_tools fields against it before creating anything from the result.

spekomcp_migration_session_config_build#Build a Speko SessionConfig draft from prose and hints.1 param▾

Build a Speko SessionConfig draft from prose and hints.

NameTypeRequiredDescription

bodyobjectrequiredJSON object describing the agent you want, used to draft a Speko SessionConfig. All fields are optional: prose is a plain-language description of what the agent should do (e.g. 'a dental clinic receptionist that books appointments and answers insurance questions'); intent carries routing metadata such as the spoken language (e.g. {"language": "en"}); workspace_context adds hints about the source codebase — repo_languages and framework_hints — to bias the draft toward compatible defaults. Any other keys you include are passed through unchanged. Example: {"prose": "A friendly pizza-shop phone agent that takes orders and quotes wait times", "intent": {"language": "en"}}.

spekomcp_migration_workspace_inspect#Inspect a voice-agent codebase and return migration recommendations.2 params▾

Inspect a voice-agent codebase and return migration recommendations.

NameTypeRequiredDescription

filesobjectrequiredMap of relative file path to full text content, for up to 60 files from the voice-agent codebase being migrated. Include only the files relevant to migration — agent configuration, prompt definitions, tool/function schemas, and call-handling code. The server never reads your filesystem; it only sees the files you send here. Example: {"agent_config.py": "AGENT = {\"voice\": \"alloy\"}", "tools.json": "[{\"name\": \"lookup_order\"}]"}.

metadataobjectoptionalOptional hints about the source codebase to sharpen the recommendations, such as repo_languages (e.g. ["python", "typescript"]) and framework_hints (e.g. ["vapi", "livekit"]). Omit to let the inspector infer these from the supplied files alone.

spekomcp_models_list#List the STT/LLM/TTS/S2S provider and model catalog. Each entry's `id` ('vendor' or 'vendor:model') is the literal string accepted by `allowedProviders` pins in agent and session configs; `benchmarked` marks entries with live Speko benchmark scores.0 params▾

List the STT/LLM/TTS/S2S provider and model catalog. Each entry's `id` ('vendor' or 'vendor:model') is the literal string accepted by `allowedProviders` pins in agent and session configs; `benchmarked` marks entries with live Speko benchmark scores.

spekomcp_operations_cancel#Request cancellation of a cancellable operation. This is a request, not a guarantee: an operation past its cancellable point keeps running. Requires speko:execute, unlike the speko:read reads in this group. Check operations.get or operations.wait afterward to see whether it actually reached "cancelled".1 param▾

Request cancellation of a cancellable operation. This is a request, not a guarantee: an operation past its cancellable point keeps running. Requires speko:execute, unlike the speko:read reads in this group. Check operations.get or operations.wait afterward to see whether it actually reached "cancelled".

NameTypeRequiredDescription

operationIdstringrequiredUUID of the durable operation to request cancellation for. Cancellation is best-effort; an operation past its cancellable point keeps running.

spekomcp_operations_get#Read one durable action operation by id, including its steps array (each with its own status and optional progress) and, once failed, an error object with a code, message and whether it is retryable. Poll this or use operations.wait to watch it settle.1 param▾

Read one durable action operation by id, including its steps array (each with its own status and optional progress) and, once failed, an error object with a code, message and whether it is retryable. Poll this or use operations.wait to watch it settle.

NameTypeRequiredDescription

operationIdstringrequiredUUID of the durable operation to read, as returned when the originating action was started.

spekomcp_operations_list#List recent durable action executions in the current workspace: the operations that run async rather than returning inline, in "claimed", "queued", "running", "succeeded", "failed" or "cancelled" status. Filter by actionId or status. Pass an id to operations.get for the full step-by-step detail.3 params▾

List recent durable action executions in the current workspace: the operations that run async rather than returning inline, in "claimed", "queued", "running", "succeeded", "failed" or "cancelled" status. Filter by actionId or status. Pass an id to operations.get for the full step-by-step detail.

NameTypeRequiredDescription

limitintegerrequiredMaximum number of operations to return, from 1 to 100. Defaults to 50 when omitted.

actionIdstringoptionalRestrict results to operations created by this action id. Omit to list operations across all actions.

statusstringoptionalRestrict results to operations in this status. Omit to include every status.

spekomcp_operations_wait#Wait briefly for a durable operation to change or reach a terminal state, up to timeoutMs (0 to 30000, default 10000). Returns as soon as the operation moves, or once the timeout elapses, whichever comes first. Returns the same shape as operations.get either way.2 params▾

Wait briefly for a durable operation to change or reach a terminal state, up to timeoutMs (0 to 30000, default 10000). Returns as soon as the operation moves, or once the timeout elapses, whichever comes first. Returns the same shape as operations.get either way.

NameTypeRequiredDescription

operationIdstringrequiredUUID of the durable operation to wait on.

timeoutMsintegerrequiredHow long to wait for the operation to change or finish, in milliseconds, from 0 to 30000. Defaults to 10000 (10 seconds) when omitted.

spekomcp_organization_get#Get the current workspace and its capability flags: features.buyPhoneNumbers, sms10dlc, smsMessaging, imessageIntegration, agentDuplication and others, each as an {enabled} object. retrievalProvider and imessageProvider are null when the corresponding integration is not configured.0 params▾

Get the current workspace and its capability flags: features.buyPhoneNumbers, sms10dlc, smsMessaging, imessageIntegration, agentDuplication and others, each as an {enabled} object. retrievalProvider and imessageProvider are null when the corresponding integration is not configured.

spekomcp_phone_numbers_available_search#Search phone numbers available to buy. Searching is read-only and always works. BUYING one does not follow from it. `phone_numbers.create` debits the workspace's prepaid credits (setup plus the first month; it is not a card payment or a checkout). OAuth connector users normally do not need this search: their first outbound call automatically purchases a dedicated US number after the phone authorization accepted at sign-in. Manual dashboard/API callers retain the declaration and purchase flow. Never collect or submit KYB fields in chat.3 params▾

Search phone numbers available to buy. Searching is read-only and always works. BUYING one does not follow from it. `phone_numbers.create` debits the workspace's prepaid credits (setup plus the first month; it is not a card payment or a checkout). OAuth connector users normally do not need this search: their first outbound call automatically purchases a dedicated US number after the phone authorization accepted at sign-in. Manual dashboard/API callers retain the declaration and purchase flow. Never collect or submit KYB fields in chat.

NameTypeRequiredDescription

area_codestringoptionalOptional 3-digit US area code to filter available numbers by, e.g. 415 for San Francisco. Omit to search all area codes.

limitintegeroptionalMaximum number of available numbers to return. Omit to use the server's default.

localitystringoptionalOptional locality or city name to filter available numbers by. Omit to search all localities.

spekomcp_phone_numbers_create#Provision a phone number.1 param▾

Provision a phone number.

NameTypeRequiredDescription

bodyobjectrequiredJSON body for POST /v1/phone-numbers. Requires e164, the number to provision in E.164 format (e.g. '+12015551234') — pick one from phone_numbers.available.search. direction controls call flow: 'inbound', 'outbound' or 'both' (default 'outbound'). label is an optional display name up to 120 characters. agentId links the number to the agent that answers inbound calls on it. dispatchMetadataTemplate is an optional object of metadata attached to inbound dispatches on this number.

spekomcp_phone_numbers_delete#Release and delete one phone number.1 param▾

Release and delete one phone number.

NameTypeRequiredDescription

phone_number_idstringrequiredUnique identifier of the phone number row to release and permanently delete, as returned by phone_numbers.list.

spekomcp_phone_numbers_get#Get one phone or SIP number owned by the current workspace. setupStatus.status is "ready" only when inboundReady, outboundReady and agentReady are all true; check the setupStatus.issues array for what is still missing. A number can also carry suspendedAt with a suspensionReason of "billing" or "compliance", which blocks calls independently of setupStatus. Use phone_numbers.list to find a number id first.1 param▾

Get one phone or SIP number owned by the current workspace. setupStatus.status is "ready" only when inboundReady, outboundReady and agentReady are all true; check the setupStatus.issues array for what is still missing. A number can also carry suspendedAt with a suspensionReason of "billing" or "compliance", which blocks calls independently of setupStatus. Use phone_numbers.list to find a number id first.

NameTypeRequiredDescription

phone_number_idstringrequiredUnique identifier (UUID) of the phone number row to retrieve, as returned by phone_numbers.list.

spekomcp_phone_numbers_kyb_get#Read this workspace's phone compliance status. OAuth connector workspaces submit automatically from the phone authorization accepted during sign-in; do not collect or submit declaration fields in chat. `submissionMode` identifies automatic OAuth, manual dashboard/API, or grandfathered migration handling.0 params▾

Read this workspace's phone compliance status. OAuth connector workspaces submit automatically from the phone authorization accepted during sign-in; do not collect or submit declaration fields in chat. `submissionMode` identifies automatic OAuth, manual dashboard/API, or grandfathered migration handling.

spekomcp_phone_numbers_list#List phone and SIP numbers owned by the current workspace. For OAuth connectors, the first outbound call automatically provisions a dedicated number from workspace credits when none exists. Manual dashboard/API users keep the explicit declaration and purchase flow.0 params▾

List phone and SIP numbers owned by the current workspace. For OAuth connectors, the first outbound call automatically provisions a dedicated number from workspace credits when none exists. Manual dashboard/API users keep the explicit declaration and purchase flow.

spekomcp_phone_numbers_update#Update one phone number.2 params▾

Update one phone number.

NameTypeRequiredDescription

bodyobjectrequiredJSON body for PATCH /v1/phone-numbers/{id}. Every field is optional and only the ones you include are changed: direction switches call flow between 'inbound', 'outbound' or 'both'; label sets a display name up to 120 characters (or null to clear it); agentId relinks the number to a different agent that answers inbound calls (or null to unlink it); dispatchMetadataTemplate replaces the metadata object attached to inbound dispatches on this number (or null to clear it).

phone_number_idstringrequiredUnique identifier of the phone number row to update, as returned by phone_numbers.list.

spekomcp_scenarios_archive#Archive a scenario — the only lifecycle transition there is. An archived scenario stops being driven by the gate but keeps its run history. Pass `superseded_by` with the id of the scenario that replaces it to record the lineage; the replacement must already exist in this organization and cannot be the scenario itself.2 params▾

Archive a scenario — the only lifecycle transition there is. An archived scenario stops being driven by the gate but keeps its run history. Pass `superseded_by` with the id of the scenario that replaces it to record the lineage; the replacement must already exist in this organization and cannot be the scenario itself.

NameTypeRequiredDescription

scenario_idstringrequiredId of the library scenario to archive.

superseded_bystringoptionalOptional id of the scenario that replaces this one. Must already exist in this organization and cannot be the same scenario being archived; recorded as the lineage for this archive.

spekomcp_scenarios_attach#Attach a library scenario to an agent so the reliability gate drives it there. Supply `persona_id` to pin the caller character this agent runs the scenario with (persona x scenario compose); pass null to clear it; omit it to leave an existing pin unchanged.3 params▾

Attach a library scenario to an agent so the reliability gate drives it there. Supply `persona_id` to pin the caller character this agent runs the scenario with (persona x scenario compose); pass null to clear it; omit it to leave an existing pin unchanged.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to attach this scenario to, as returned by agents.create or agents.list.

scenario_idstringrequiredId of the library scenario to attach to the agent, as returned by scenarios.create or scenarios.list.

persona_idstringoptionalOptional caller persona to pin for this agent-plus-scenario pairing. Pass one of the supported persona ids to set it, explicit null to clear an existing pin, or omit the field entirely to leave any existing pin unchanged.

spekomcp_scenarios_create#Author a scenario into the organization library and optionally attach it to agents. Deduped by content: an identical scenario already in the org (for example one the reliability gate derived) is reused and only the attachments are added, so re-running this never creates a twin. Scenario content is FROZEN at creation — there is no update action by design; evolve a scenario by creating a new one and calling scenarios.archive on the old one with superseded_by.6 params▾

Author a scenario into the organization library and optionally attach it to agents. Deduped by content: an identical scenario already in the org (for example one the reliability gate derived) is reused and only the attachments are added, so re-running this never creates a twin. Scenario content is FROZEN at creation — there is no update action by design; evolve a scenario by creating a new one and calling scenarios.archive on the old one with superseded_by.

NameTypeRequiredDescription

caller_goalstringrequiredWhat the simulated caller wants to achieve in this scenario, used to drive the caller persona's behavior during a run.

jobstringrequiredThe task the caller is trying to complete.

success_criteriastringrequiredThe bar the agent must clear for this scenario to count as passed.

agent_idsarrayoptionalOptional list of up to 64 agent ids to attach this new scenario to immediately, so the reliability gate starts driving it on those agents right away.

behaviorstringoptionalOptional frozen caller-behavior tag.

required_toolstringoptionalOptional name of a tool the agent must call for this scenario to pass, e.g. a booking or lookup tool registered on the agent.

spekomcp_scenarios_detach#Detach a library scenario from one agent. The scenario itself and its history survive — only the agent link is removed.2 params▾

Detach a library scenario from one agent. The scenario itself and its history survive — only the agent link is removed.

NameTypeRequiredDescription

agent_idstringrequiredId of the agent to detach the scenario from.

scenario_idstringrequiredId of the library scenario to detach from the agent. The scenario itself keeps its history and remains available in the library.

spekomcp_scenarios_list#List the organization scenario library, newest first. A scenario is one thing a caller is trying to do, reusable across agents. Pass `agent_id` to list only the scenarios attached to that agent.1 param▾

List the organization scenario library, newest first. A scenario is one thing a caller is trying to do, reusable across agents. Pass `agent_id` to list only the scenarios attached to that agent.

NameTypeRequiredDescription

agent_idstringoptionalOptional id of the agent to filter to; when set, only scenarios attached to this agent are returned. Omit to list the entire organization scenario library.

spekomcp_scenarios_runs_list#List up to 50 recent reliability runs that exercised this scenario, each with the per-scenario verdict it produced — the scenario track record across agent versions. Only runs written after the gate began stamping scenarioId carry the link, so older runs will not appear.1 param▾

List up to 50 recent reliability runs that exercised this scenario, each with the per-scenario verdict it produced — the scenario track record across agent versions. Only runs written after the gate began stamping scenarioId carry the link, so older runs will not appear.

NameTypeRequiredDescription

scenario_idstringrequiredId of the library scenario whose recent reliability runs to list.

spekomcp_sessions_create#Create a browser/WebRTC or server-to-server voice session.1 param▾

Create a browser/WebRTC or server-to-server voice session.

NameTypeRequiredDescription

bodyobjectrequiredJSON object for the session configuration sent to POST /v1/sessions. Provide either agentId (reuse a saved agent's settings) or an intent object with a BCP-47 language code (region and optimizeFor are optional) — unless mode is 's2s' with a provider and model already pinned under the s2s object, in which case neither is required. Optional fields let you override the session's mode (cascade or s2s), voice, systemPrompt, firstMessage, LLM sampling (temperature, maxTokens), TTS and STT provider options, background and tool-call ambience sounds, allowed-provider constraints, arbitrary metadata, session TTL in seconds (capped at 86400, default 900), and a caller identity string. When mode is 's2s', add an s2s object with the speech-to-speech provider, model, voice, sampling and tool definitions; s2s sessions cap ttlSeconds at 3600 (default 1800). Any field you pass overrides the referenced agent's saved defaults for this call only. Example: {"agentId": "agt_1a2b3c4d5e6f", "voice": "warm-female-1", "firstMessage": "Hi, thanks for calling!", "ttlSeconds": 600}

spekomcp_sessions_get#Get one session.1 param▾

Get one session.

NameTypeRequiredDescription

session_idstringrequiredSession id.

spekomcp_sessions_list#List sessions for the authenticated organization.7 params▾

List sessions for the authenticated organization.

NameTypeRequiredDescription

agentstringoptionalOptional agent id filter.

cursorstringoptionalISO cursor from the previous page.

from_stringoptionalOptional ISO start timestamp.

kindstringoptionalOptional kind filter: cascade or s2s.

limitintegeroptionalMaximum sessions to return.

statusstringoptionalOptional status filter.

tostringoptionalOptional ISO end timestamp.

spekomcp_sessions_phone_create#Create an outbound phone session, dialing `body.to` from an owned or auto-provisioned number. This tool has the highest error rate on this surface. Read the failure modes below before retrying. A rejected call returns one of these codes in the error body: AGENT_NOT_FOUND (agentId not in this workspace), PHONE_NUMBER_CONSENT_REQUIRED (the connector's phone-use authorization needs reacceptance), PHONE_NUMBER_KYB_ACCESS_SUSPENDED (compliance review pending, retrying will not help; check phone_numbers.kyb.get for status), PHONE_NUMBER_PROVISIONING_CREDITS_REQUIRED, _PENDING, and _FAILED (auto-provisioning a number failed or needs credit; see the returned balance and price fields), and INSUFFICIENT_CREDITS. A 2xx response does not mean the call was answered. No-answer, voicemail, and carrier rejection all settle normally and appear afterward in get_call or sessions.transcript.get, not as a tool error here. A 403 with code PHONE_NUMBER_SCOPE_REQUIRED means this connection predates phone calling and needs a full reconnect (a token refresh cannot add the permission). A 403 with code PHONE_NUMBER_CONSENT_REQUIRED means the workspace needs to accept the phone-use consent screen instead - no reconnect needed. `body.voice`, if set, is not validated against what the selected TTS provider owns before dialing. An unrecognized or foreign voice id can produce a dead-air leg with no error. Omit `voice` unless it came from this agent's own configuration; there is no voice-lookup tool on this profile.1 param▾

Create an outbound phone session, dialing `body.to` from an owned or auto-provisioned number. This tool has the highest error rate on this surface. Read the failure modes below before retrying. A rejected call returns one of these codes in the error body: AGENT_NOT_FOUND (agentId not in this workspace), PHONE_NUMBER_CONSENT_REQUIRED (the connector's phone-use authorization needs reacceptance), PHONE_NUMBER_KYB_ACCESS_SUSPENDED (compliance review pending, retrying will not help; check phone_numbers.kyb.get for status), PHONE_NUMBER_PROVISIONING_CREDITS_REQUIRED, _PENDING, and _FAILED (auto-provisioning a number failed or needs credit; see the returned balance and price fields), and INSUFFICIENT_CREDITS. A 2xx response does not mean the call was answered. No-answer, voicemail, and carrier rejection all settle normally and appear afterward in get_call or sessions.transcript.get, not as a tool error here. A 403 with code PHONE_NUMBER_SCOPE_REQUIRED means this connection predates phone calling and needs a full reconnect (a token refresh cannot add the permission). A 403 with code PHONE_NUMBER_CONSENT_REQUIRED means the workspace needs to accept the phone-use consent screen instead - no reconnect needed. `body.voice`, if set, is not validated against what the selected TTS provider owns before dialing. An unrecognized or foreign voice id can produce a dead-air leg with no error. Omit `voice` unless it came from this agent's own configuration; there is no voice-lookup tool on this profile.

NameTypeRequiredDescription

bodyobjectrequiredJSON object for POST /v1/sessions/phone. Requires `to`, the E.164 number to dial, plus either agentId (a saved agent) or an intent object with a language code. Optional: from (an owned E.164 number; an OAuth-connected workspace with no number yet gets one auto-provisioned from credits on this call when agentId is present), runMode (cascade or s2s — s2s hosts the call on a speech-to-speech model instead of an STT/LLM/TTS cascade, and overrides the agent's saved run mode), voice, systemPrompt, firstMessage, LLM sampling, TTS and STT provider options, telephony settings (region, answering-machine detection), allowed-provider constraints, and metadata. Per-call fields override the agent's saved defaults. Leave voice unset unless it is a value already configured on the target agent — an unrecognized or unowned voice id is accepted here but can produce dead air or fail silently downstream. Do not collect KYB fields yourself. Example: {"to": "+12015551234", "agentId": "agt_1a2b3c4d5e6f"}

spekomcp_sessions_recording_get#Get a signed recording URL for one session.1 param▾

Get a signed recording URL for one session.

NameTypeRequiredDescription

session_idstringrequiredUnique identifier of the session to get a signed, time-limited recording URL for, as returned by calls.get or agents.calls.list.

spekomcp_sessions_transcript_get#Get the ordered transcript and per-turn latency for a workspace session, including any tool calls made mid-call (toolCalls, by name and args) and a latencyStatus per turn ("partial"|"complete"|"interrupted"|"error"). Use this to confirm whether a keypad press (send_dtmf) was invoked, or whether a turn with no agent text and an "error" latency status points to a synthesis failure rather than the callee hanging up.1 param▾

Get the ordered transcript and per-turn latency for a workspace session, including any tool calls made mid-call (toolCalls, by name and args) and a latencyStatus per turn ("partial"|"complete"|"interrupted"|"error"). Use this to confirm whether a keypad press (send_dtmf) was invoked, or whether a turn with no agent text and an "error" latency status points to a synthesis failure rather than the callee hanging up.

NameTypeRequiredDescription

session_idstringrequiredUnique identifier (UUID) of the workspace session whose transcript to retrieve, as returned by calls.get or agents.calls.list.

spekomcp_share_cards_create#Create a public share card for an agent build.2 params▾

Create a public share card for an agent build.

NameTypeRequiredDescription

build_idstringrequiredId of the AgentVersion or agent to create a public share card for.

titlestringoptionalTitle to display on the public share card. Omit to use a default title.

spekomcp_usage_summary_get#Get workspace usage, managed cost and current balance. from_ and to bound the window; omit both for all-time. breakdown lists cost per provider and metric, with keySource "BYOK" or "MANAGED" showing whether the workspace supplied its own provider key for that line.2 params▾

Get workspace usage, managed cost and current balance. from_ and to bound the window; omit both for all-time. breakdown lists cost per provider and metric, with keySource "BYOK" or "MANAGED" showing whether the workspace supplied its own provider key for that line.

NameTypeRequiredDescription

from_stringoptionalStart of the usage window as an ISO 8601 datetime. Omit both from_ and to to get all-time usage.

tostringoptionalEnd of the usage window as an ISO 8601 datetime. Omit both from_ and to to get all-time usage.

spekomcp_voices_list#List the Speko TTS voice catalog: voices (vendor, id, name) plus TTS providers with their models. Use a returned voice id as the `voice` field on agents.create or POST /v1/sessions bodies.1 param▾

List the Speko TTS voice catalog: voices (vendor, id, name) plus TTS providers with their models. Use a returned voice id as the `voice` field on agents.create or POST /v1/sessions bodies.

NameTypeRequiredDescription

providerstringoptionalOptional TTS provider filter, e.g. 'cartesia', 'elevenlabs', 'openai', 'inworld'. Omit to list every voice.