Current - 2026/09
Endpoint
GET
/v2/stable/mcp-server

Returns every MCP server in the environment. An MCP server is a registered Model Context Protocol server whose tools an agent can call; header values read back as [redacted]. 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).

Response

200 - application/json

Returns every MCP server connected to the project's environment, each with its URL, description, icon, and the MCP specification version it was registered against.

mcpServers
object[]
required
StableMCPServerV2 — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/mcp-server

Adds an MCP server to the environment, a registered Model Context Protocol server whose tools an agent can call. The URL and header values are plain strings that can reference a project secret as {secret_name}, and the response carries the ID that later calls address it by.

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

Request body

name
string
required
description
string

A human-readable description of what the MCP server provides.

url
object
required

Plain text resolved at runtime and never shown to a model. {variable_name} inserts a variable or entity, {secret_name} a project secret, {variable_name.path} a field of a variable. Escape a literal { or \ with a backslash. When a name is both a variable and a secret, the secret wins. A name matching none is stored as literal text and reported in unresolvedReferences. Where the field is sent to an upstream system, an unresolved placeholder may be sent as literal text; on an MCP server it is re-resolved by name at connect time, so a literal that matches a real secret binds.

DefaultValueString — see its attributes above
headers
object[]
specification
object
default:"2025-06-18"

Response

201 - application/json

Creates the connection to the MCP server and returns it with its generated ID, URL, and specification version. The tools the server exposes are read through the MCP tool endpoints.

mcpServer
object
required
StableMCPServerV2 — see its attributes above
unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Endpoint
DELETE
/v1/stable/mcp-server/{serverID}

Deletes a single MCP server by ID. A MCP server is a registered Model Context Protocol server whose tools an agent can call. The response carries only a confirmation message, so refetch the MCP servers to see what is left.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

serverID
string
required

The ID of the MCP server 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

Confirms the MCP server connection was removed from the project. The body is a message only, so refetch the project's MCP servers and tools to see what is left.

message
string
required

A human-readable message confirming the deletion.

Current - 2026/09
Endpoint
GET
/v2/stable/mcp-server/{serverID}

Returns a single MCP server by ID, with the fields that define it. An MCP server is a registered Model Context Protocol server whose tools an agent can call; its header values read back as [redacted].

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

serverID
string
required

The ID of the MCP server 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 server's stored configuration: its name, URL, description, icon, and specification version.

mcpServer
object
required
StableMCPServerV2 — see its attributes above
Current - 2026/09
Endpoint
PATCH
/v2/stable/mcp-server/{serverID}

Changes an existing MCP server in place, taking URL and header values as plain strings that can reference a project secret as {secret_name}. The response lists any references that did not resolve; read the server again to see its new values.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

serverID
string
required

The ID of the MCP server 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).

Request body

name
string
description
string

A human-readable description of what the MCP server provides.

specification
object
url
object
headers
object[]

Response

200 - application/json

Confirms the server's connection details were updated. The body is a message only, so refetch the server to read its current URL, description, and specification version.

message
string
required

A human-readable message confirming the update.

unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Endpoint
PUT
/v1/stable/mcp-server/{serverID}/sync

Refreshes the stored list of tools an MCP server advertises, which is how MCP tools come to exist rather than being created by hand.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

serverID
string
required

The ID of the MCP server 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

Confirms the sync ran against the server. The body is a message and does not itemise what changed, so list the project's MCP tools to see the server's current set.

message
string
required

A human-readable message confirming the update.

Schemas

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