Endpoint
GET
/v1/stable/mcp-tool

Returns every MCP tool in its server. A MCP tool is a tool an MCP server advertises, populated by syncing the server rather than by hand. The call takes no paging parameters, so one request yields the whole set.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

serverID
string

When provided, only tools belonging to the MCP server with this ID are returned.

Response

200 - application/json

Returns every MCP tool available in the project's environment, each with the name, description, and input JSON Schema its server declared, plus the ID of the server it came from. Pass serverID to narrow the list to one server.

mcpTools
object[]
required
StableMCPTool — see its attributes above
Endpoint
GET
/v1/stable/mcp-tool/{toolID}

Returns a single MCP tool by ID, with the fields that define it. A MCP tool is a tool an MCP server advertises, populated by syncing the server rather than by hand.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the tool to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Returns one MCP tool with the name and description its server declared and the JSON Schema for its input arguments. MCP tools are defined on the server itself, so these records are read-only in Voiceflow.

mcpTool
object
required
StableMCPTool — see its attributes above
Endpoint
GET
/v1/stable/mcp-tool/{toolID}/schema

Returns the arguments an MCP tool takes, both as a flat list of its top-level arguments and as its full JSON Schema. Call it before executing so the arguments match the tool's types.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the MCP tool whose arguments to read.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Returns the ID of the MCP server the tool belongs to, its top-level arguments, and its full JSON Schema.

serverID
string
required

The ID of the MCP server the tool belongs to.

inputs
object[]
required

The tool's top-level arguments, read from its JSON Schema.

StableExecuteInput — see its attributes above
inputSchema
object
required

The tool's full JSON Schema, for nested arguments the flat list cannot show.

Use this operation to test agent behavior or execute tools with controlled inputs. For production conversation integrations, use the Agent runtime. Tool execution can affect connected services.
Endpoint
POST
/v1/stable/mcp-tool/{toolID}/execute

Calls one MCP tool on its server with the arguments in the body, using the server's saved URL, headers, and authorization. No conversation is involved.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the MCP tool to execute.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

inputs
object

The tool's arguments, keyed by argument name and typed as its JSON Schema says; see get_schema. A top-level string value follows the ExecuteInputString rules, so {secret_name} inserts a project secret. Secrets work only at the top level: inside a nested object or array, {secret_name} is sent as written and no secret is filled in.

Response

200 - application/json

Returns what the MCP server answered, with success, latencyMs, and error fields. Secret values read [secret] wherever they appear.

success
boolean
required

Whether the tool ran and reported no error.

latencyMs
number
required

How long the run took, in milliseconds, measured by this API around the call.

error
string
required

Why the run failed when success is false, otherwise null. Secret values read [secret].

truncated
boolean
required

Whether a returned payload was over 64 KB and was cut to its first 64 KB of JSON text, which then arrives as a string.

output
any
required

What the MCP server returned. A result with isError: true fails the run and keeps this output. Null when the call itself failed or did not answer in time. Secret values read [secret].

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.