> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

API operations for mcp tools. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List MCP tools

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.

### Endpoint

```http
GET /v1/stable/mcp-tool
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `serverID`

Optional · string

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

```json
{
  "description": "When provided, only tools belonging to the MCP server with this ID are returned.",
  "type": "string"
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableMCPToolListResponse"
}
```

Example:

```json
{
  "mcpTools": [
    {
      "id": "<string>",
      "name": "<string>",
      "serverID": "<string>",
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "description": "<string>",
      "inputSchema": {}
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=<projectID>&environmentAlias=<environmentAlias>&serverID=<serverID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=<projectID>&environmentAlias=<environmentAlias>&serverID=<serverID>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=<projectID>&environmentAlias=<environmentAlias>&serverID=<serverID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf mcp-tool list --project-id <projectID> --environment-alias <environmentAlias> --server-id <serverID>
```


## Get MCP tool

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.

### Endpoint

```http
GET /v1/stable/mcp-tool/{toolID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `toolID`

Required · string

The ID of the tool to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableMCPToolResponse"
}
```

Example:

```json
{
  "mcpTool": {
    "id": "<string>",
    "name": "<string>",
    "serverID": "<string>",
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "description": "<string>",
    "inputSchema": {}
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf mcp-tool get --tool-id <toolID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Get MCP tool 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.

### Endpoint

```http
GET /v1/stable/mcp-tool/{toolID}/schema
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `toolID`

Required · string

The ID of the MCP tool whose arguments to read.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableMCPToolSchemaReadResponse"
}
```

Example:

```json
{
  "serverID": "<string>",
  "inputs": [
    {
      "name": "<string>",
      "type": "<string>",
      "required": true,
      "description": "<string>"
    }
  ],
  "inputSchema": {}
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>/schema?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>/schema?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>/schema?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf mcp-tool get-schema --tool-id <toolID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Execute MCP tool

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.

### Endpoint

```http
POST /v1/stable/mcp-tool/{toolID}/execute
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `toolID`

Required · string

The ID of the MCP tool to execute.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableMCPToolExecuteRequest"
      }
    }
  }
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableMCPToolExecuteResponse"
}
```

Example:

```json
{
  "success": true,
  "latencyMs": 0,
  "error": "<string>",
  "truncated": true,
  "output": null
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>/execute?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inputs": {}
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>/execute?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "inputs": {}
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/mcp-tool/<toolID>/execute?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "inputs": {}
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf mcp-tool execute --tool-id <toolID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "inputs": {}
}
JSON
```


## Schema definitions

### StableExecuteInput

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The input name, used as its key in `inputs` when executing."
    },
    "type": {
      "type": "string",
      "description": "The JSON type the value must have, such as `string`, `number` or `boolean`. Always `string` for a function or an API tool, and `any` when an MCP tool does not say."
    },
    "required": {
      "type": "boolean",
      "description": "Whether execute needs a value for this input."
    },
    "description": {
      "nullable": true,
      "description": "What the input holds, as the tool describes it.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "type",
    "required",
    "description"
  ]
}
```

### StableMCPTool

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "description": "The name of the tool as exposed by the MCP server."
    },
    "serverID": {
      "type": "string",
      "description": "The ID of the MCP server this tool belongs to."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "description": {
      "nullable": true,
      "description": "A human-readable description of what the tool does, as provided by the MCP server.",
      "type": "string"
    },
    "inputSchema": {
      "type": "object",
      "additionalProperties": {},
      "description": "The JSON Schema describing the tool's input arguments."
    }
  },
  "required": [
    "id",
    "name",
    "serverID",
    "createdAt",
    "updatedAt",
    "description",
    "inputSchema"
  ]
}
```

### StableMCPToolExecuteRequest

```json
{
  "type": "object",
  "properties": {
    "inputs": {
      "default": {},
      "description": "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.",
      "type": "object",
      "additionalProperties": {}
    }
  },
  "additionalProperties": false
}
```

### StableMCPToolExecuteResponse

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the tool ran and reported no error."
    },
    "latencyMs": {
      "type": "number",
      "description": "How long the run took, in milliseconds, measured by this API around the call."
    },
    "error": {
      "nullable": true,
      "description": "Why the run failed when `success` is false, otherwise null. Secret values read `[secret]`.",
      "type": "string"
    },
    "truncated": {
      "type": "boolean",
      "description": "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": {
      "description": "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]`."
    }
  },
  "required": [
    "success",
    "latencyMs",
    "error",
    "truncated",
    "output"
  ]
}
```

### StableMCPToolListResponse

```json
{
  "type": "object",
  "properties": {
    "mcpTools": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableMCPTool"
      }
    }
  },
  "required": [
    "mcpTools"
  ]
}
```

### StableMCPToolResponse

```json
{
  "type": "object",
  "properties": {
    "mcpTool": {
      "$ref": "#/components/schemas/StableMCPTool"
    }
  },
  "required": [
    "mcpTool"
  ]
}
```

### StableMCPToolSchemaReadResponse

```json
{
  "type": "object",
  "properties": {
    "serverID": {
      "type": "string",
      "description": "The ID of the MCP server the tool belongs to."
    },
    "inputs": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableExecuteInput"
      },
      "description": "The tool's top-level arguments, read from its JSON Schema."
    },
    "inputSchema": {
      "type": "object",
      "additionalProperties": {},
      "description": "The tool's full JSON Schema, for nested arguments the flat list cannot show."
    }
  },
  "required": [
    "serverID",
    "inputs",
    "inputSchema"
  ]
}
```
