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

# n8n integration

> Connect Voiceflow to n8n to run an approved workflow and return its delivery information to the customer.

## Overview

Voiceflow integrates with n8n so your AI agent can run an approved workflow and return its delivery information to the customer. n8n runs the external workflow; Voiceflow calls its approved endpoint and uses the response in the conversation.

### Examples of when to use n8n

- **[Run an approved workflow](#run-workflow)** — choose Webhook or MCP for its connection and result.
- **[Return a delivery update](#run-workflow)** — invoke the configured service and interpret its current result.
- **[Recover a failed request](#maintaining-the-connection)** — inspect execution and downstream state before retrying.

#### Studio

Use an editable test project in [Agent studio](https://creator.voiceflow.com). Your integration developer or administrator prepares the service below, supplies its endpoint and credentials, and gives you a verified test request plus its expected result. Keep provider-side deployment with that owner.

#### Developer

Use a [Voiceflow personal or service key](/docs/api-reference/authentication) with project access, a current [Voiceflow CLI](/docs/cli/install) and the selected test [Environment](/docs/documentation/deploy/environments/overview). You prepare the provider service and create, execute and attach the Voiceflow request separately. The examples use a test project; they can read or change connected systems.

<a id="run-workflow"></a>

## Run a workflow

Choose the interface exposed by your approved n8n workflow.

Use **Webhook** when you expose an HTTP request and choose its response mode. Use **MCP** when you expose a workflow as a named tool. Both methods below retrieve the same delivery result; configure the one your workflow uses. The n8n owner provisions its host, workflow and trigger credential, and supplies a verified request/response before Voiceflow setup.

#### Webhook

Invoke **Check delivery with n8n** when the customer asks where their order is. The authenticated application supplies the verified identity and prepared request variable before the call; keep those inputs bound to trusted defaults. Use the returned order ID, delivery status and estimated delivery only after confirming they belong to the requested order. For a pending result, explain that work is waiting. For a current failure or missing required fields, say the result could not be confirmed; never reuse an earlier result or automatically repeat an uncertain write.

### Prepare the provider service

#### Studio

Ask your n8n administrator or integration developer to complete the service setup linked below. Obtain all four handoff items before creating the Voiceflow tool:

- The deployed HTTPS endpoint and its exact authentication headers.
- The credential value for the Voiceflow Secret.
- A request schema, response schema and verified test customer/resource.
- A successful test response and a rejected unauthorized request, confirmed in the provider's execution history.

The sample request fields on this page are a recipe contract for your existing workflow. Have the owner map them to that workflow; a provider account alone does not create this endpoint.

#### Developer

### 1. Configure the Webhook trigger

In the n8n workflow, add **Webhook**, choose **POST** and set the path to `check-delivery`. Select **Header auth** and create a credential whose header name is `X-Voiceflow-Key` with a generated secret value. This credential belongs to this webhook, not n8n's administrative API. Use n8n Cloud or a self-hosted HTTPS endpoint reachable from Voiceflow.

### 2. Map and return the approved result

Read `customer_id` and `order_id` from the Webhook request body. Validate the caller's customer/order access, then run your existing delivery lookup workflow. Set **Respond → Using 'Respond to Webhook' Node** and add **Respond to Webhook** after the lookup, returning one JSON object with `order_id`, `status` and `estimated_delivery`. Configure error paths deliberately; **Respond Immediately** only acknowledges that the workflow started.

### 3. Publish and verify the production URL

Publish the workflow and copy its **Production URL**. The Test URL is registered while **Listen for Test Event** or the editor's test execution is active; do not leave an agent pointing to that temporary listener. Test the production endpoint with a verified order, inspect **Executions** and verify the returned JSON against the business system. Also test missing credentials and an unauthorized order.

Provider setup: [Webhook authentication and response modes](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/) and [Respond to Webhook](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.respondtowebhook/).

### Create the Voiceflow request

#### Studio

### 1. Store the service credential

Open your test project in [Agent studio](https://creator.voiceflow.com), then **More → Secrets**. Create `n8n_webhook_token` with the credential supplied by the service owner. Creating its default also writes Main's Published value, so keep initial setup in a test project. If the selected Environment has a different Draft credential, set its Draft override too.

### 2. Create a request variable

Open **More → Variables**, create `n8n_request` with an empty default and ask your application developer to populate it with the [prepared request](#run-workflow). For a Studio Run test, temporarily set its default to the developer's prepared test string in this isolated test project; backend runtime variables do not automatically populate Studio Run. Clear the default after that test.

### 3. Configure the API request

Open **Agent → Global tools → + → API** and name the tool **Check delivery with n8n**. Choose **POST**, set the owner-supplied endpoint and add the headers below. Set the raw JSON body to `{payload}`.

| Field | Value |
| --- | --- |
| Name | `Check delivery with n8n` |
| Method | `POST` |
| URL | `https://YOUR_N8N/webhook/check-delivery` |
| Header: X-Voiceflow-Key | `{authorization}` |
| Header: Content-Type | `application/json` |
| Raw JSON body | `{payload}` |

Native n8n API request editor with configured endpoint, headers and raw request body — Configure the deployed n8n endpoint and its request fields.

### 4. Bind inputs before running

Open the attached tool's inputs. Open `authorization` and set its **Default value** to the Secret `n8n_webhook_token`, and set `payload`'s **Default value** to `n8n_request`. Keep **Async execution** off so the agent receives this call's response. The provider workflow may still return a pending receipt.

#### Developer

Set `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT` for the test project. Set `PROVIDER_CREDENTIAL` to the API Platform Auth Token. The service owner supplies `PROVIDER_URL` and the verified test request.

Save this definition as `n8n-tool.json`, replacing the illustrative URL with `PROVIDER_URL`. Braced names declare inputs on this API tool; they are bound to Secrets/variables on its attachment later.

```json
{
  "name": "Check delivery with n8n",
  "description": "Run the approved n8n request for the customer verified by the application.",
  "httpMethod": "post",
  "url": "https://YOUR_N8N/webhook/check-delivery",
  "headers": [
    {
      "key": "X-Voiceflow-Key",
      "value": "{authorization}"
    },
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "body": {
    "type": "raw-input",
    "contentType": "json",
    "content": "{payload}"
  }
}
```

#### API

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"n8n_webhook_token",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"n8n_request","color":"#515A63","defaultValue":""}'

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @n8n-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`, then discover input IDs:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$API_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"n8n_webhook_token",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json

vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name n8n_request --color-param '#515A63' --default-value '""' --output-format json

vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < n8n-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`, then discover input IDs:

```sh
vf api-tool variable list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --api-tool-id "$API_TOOL_ID" --output-format json

vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json
```

Creating the Secret default also writes Main's Published value. If your selected Environment uses a different credential, set its [Draft override](/docs/documentation/build/data/secrets#publishing-reverting-and-discarding-changes) before testing. Match each `variables[].name` to its `id` for the attachment; resolve `unresolvedReferences` before continuing.

### Prepare the request

#### Developer

The application developer builds the request from an authenticated customer/resource and the confirmed task. Save this illustrative body as `n8n-request.json`, replacing test identities with values the application has verified:

```json
{
  "customer_id": "verified-customer-123",
  "order_id": "order-test-1042"
}
```

Serialize it with the [literal-safe request encoder](/docs/examples/automation/encode-request.mjs): `node encode-request.mjs n8n-request.json > n8n-payload.txt`. It preserves quotes, newlines and literal text such as `{customer_name}` without treating that text as a Voiceflow variable or Secret. Do not concatenate customer text into quoted JSON placeholders.

#### Studio

Have your developer deliver the encoded string and populate `n8n_request` in the authenticated client's next action **before** this tool runs. They send `variables` on the [runtime action](/docs/api-reference/v4interact/interact-non-stream#streaming-action); creating the variable or session alone does not fill it. For Studio Run, use the temporary test default described above, then clear it. The provider service must enforce customer access and validate the request; tool descriptions do not enforce either.

#### Developer

Read the confirmed body, encode it, and build standalone inputs. This tests the saved request against the selected Environment's Draft; it does not attach the tool or publish the agent.

```sh
node encode-request.mjs n8n-request.json > n8n-payload.txt
jq -n --rawfile payload n8n-payload.txt \
  '{inputs:{authorization:"{n8n_webhook_token}",payload:$payload}}' > n8n-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @n8n-inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < n8n-inputs.json
```

Require `success: true`, inspect `output.status` and `output.body`, and check the business fields against the service owner's response schema. `truncated: true` means the returned body is incomplete. On timeout or error, inspect provider execution before retrying a write.

### Let the agent use the request

#### Studio

### 1. Describe the trigger and result use

Open the attached **Check delivery with n8n** tool and set **Trigger** to the condition below. Its input defaults must already point to the Secret and prepared request variable; the model must not collect credentials or choose another customer's identifier.

```markdown
Use Check delivery with n8n when the customer asks for this service and the application has supplied the verified request. Use the order verified by the application.
Read the current tool result. Report only the returned order status and estimated delivery.
If the response is pending, say the request is pending. If the call fails or the required fields are missing, explain that the result could not be confirmed. Never reuse an earlier result or automatically repeat a write.
```

### 2. Test the conversation

In **Run**, use the verified test request. Ask "Where is my order?" and confirm the intended tool runs with the fixed identity and prepared payload. Inspect the current tool result in Run and compare it with the order in the business system. Also test the rejected-resource case: the agent must not claim success or expose another customer's data.

#### Developer

Save this as `n8n-attachment.json`. Replace `YOUR_API_TOOL_ID` and each input ID with the values discovered above. The payload and credential are defaults, not model-collected inputs.

```json
{
  "type": "api",
  "apiToolID": "YOUR_API_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Use when the customer asks where their order is, after the application supplies the verified customer and order request. Answer from the current matching order_id, status and estimated_delivery. Explain pending, missing or failed results without reusing an earlier response.",
  "asyncExecution": false,
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTHORIZATION_INPUT_ID",
      "required": false,
      "defaultValue": "{n8n_webhook_token}"
    },
    "payload": {
      "apiToolInputVariableID": "PAYLOAD_INPUT_ID",
      "required": false,
      "defaultValue": "{n8n_request}"
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @n8n-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < n8n-attachment.json
```

Your authenticated backend supplies the encoded payload as `variables.n8n_request` on the next [runtime action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). Use a test client bound to this project's Draft, ask for the order status and inspect the emitted tool call, current response and agent answer. Verify both the successful and rejected-resource cases. The backend/provider enforces access; the description is model guidance, not an authorization gate.

The attached API tool returns the provider body to the agent. For a Workflow's **Capture response**, paths start at that body: for example `status` rather than standalone `output.body.status`. A missing capture can leave an earlier variable value unchanged; clear result variables before a Workflow call and branch on the current HTTP/business outcome. These Global tool examples use the current result directly.

#### MCP

Invoke **the approved n8n delivery tool** when the customer asks where their order is. The authenticated application supplies the verified identity and prepared request variable before the call; keep those inputs bound to trusted defaults. Use the returned order ID, delivery status and estimated delivery only after confirming they belong to the requested order. For a pending result, explain that work is waiting. For a current failure or missing required fields, say the result could not be confirmed; never reuse an earlier result or automatically repeat an uncertain write.

### Prepare the MCP request

#### Developer

Build this request from the customer and order verified by your application. Download [encode-request.mjs](/docs/examples/automation/encode-request.mjs), save the confirmed body as `n8n-request.json`, then run `node encode-request.mjs n8n-request.json > n8n-payload.txt`. The n8n workflow's `payload` input is explicitly a string; parsing it inside the sub-workflow restores literal customer text without Voiceflow interpreting it as a reference.

```json
{
  "customer_id": "verified-customer-123",
  "order_id": "order-test-001"
}
```

#### Studio

### 1. Obtain the prepared workflow tool

Ask your n8n developer to prepare the MCP workflow described in the provider setup links below. Obtain the published MCP Server Trigger's **Production URL**, its Bearer credential, and the approved delivery tool name. The tool must accept one string named `payload`, parse the prepared JSON, check customer/order access and return `order_id`, `status` and `estimated_delivery`. Ask the owner to confirm a successful delivery lookup and a rejected customer/order pair in Executions before connecting Voiceflow. This credential belongs to the trigger; it is separate from the n8n administrative API key.

Provider setup: [MCP Server Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.mcptrigger/) and [Call n8n Workflow Tool](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolworkflow/).

### 2. Store the connection credential

In your test project in [Agent studio](https://creator.voiceflow.com), open **More → Secrets** and create `n8n_mcp_token`. Set its default to the provider token: design-time MCP discovery uses the project default. Creating it also sets Main's Published value, so perform initial setup in a test project. If the selected Environment has its own Draft override, fill that too.

### 3. Connect the MCP server

Open **Agent → Global tools → + → MCP → Create MCP tool**. Name it **n8n**, use `https://YOUR_N8N/mcp/YOUR_PATH`, and add `Authorization` with `Bearer {n8n_mcp_token}` as a Secret reference. Select **Add MCP server**, then select only the approved business tool. A tool catalog is not proof that the connected account may execute every listed operation.

Native Add MCP server dialog for the n8n connection — Connect the hosted n8n server with its authorization header.

### 4. Configure invocation and inputs

Open the attached tool and write a **Trigger** for **Where is my order?**. Create `n8n_request` in **More → Variables** with an empty default. Have your authenticated application developer supply the literal-safe JSON request string on the next runtime action, then bind the `payload` input default to that variable. The n8n workflow must parse that string and enforce access before its business operation.

### 5. Test a real conversation path

In the isolated project's **Run**, ask **Where is my order?**. For this Run test, temporarily set the request variable default to the developer-supplied test string, since backend action variables do not populate Studio Run. Clear it afterward. Confirm the intended tool runs, inspect its current result and compare it with the provider's execution history. Tell the agent to answer only from the current successful result. For missing data, an error or a pending response, it must explain that state without inventing completion. Test that failure case as well.

#### Developer

Set `VF_TOKEN` to your [Voiceflow API credential](/docs/api-reference/authentication), `PROJECT_ID` to the test project and `ENVIRONMENT` to its test alias. Set `PROVIDER_TOKEN` to the token prepared below. The [current CLI](/docs/cli/install) reads `VF_TOKEN`.

### 1. Create the MCP trigger

In n8n, add **MCP Server Trigger**, choose **Bearer auth** and create its credential. Keep this credential separate from your n8n API key. This trigger connects to tool nodes, rather than an ordinary chain of action nodes.

### 2. Expose the delivery workflow's input

Attach **Call n8n Workflow Tool** to the trigger and select the approved delivery sub-workflow. Define one string `payload` in that sub-workflow's input schema. In **Call n8n Workflow Tool → Workflow Inputs**, select **Refresh**, then enable **Let the model define this parameter** for `payload` so it appears in the MCP schema.

The sub-workflow parses that JSON string, checks the verified customer/order access and returns `order_id`, `status` and `estimated_delivery`.

### 3. Publish and verify the endpoint

Publish both workflows and copy the trigger's **Production URL**. Verify the tool's input schema, successful delivery result and rejected customer/order case before connecting Voiceflow. See [MCP Server Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.mcptrigger/) and [Call n8n Workflow Tool](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolworkflow/).

Save this as `n8n-server.json`, replacing the illustrative n8n URL when applicable:

```json
{
  "name": "n8n",
  "url": "https://YOUR_N8N/mcp/YOUR_PATH",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {n8n_mcp_token}"
    }
  ]
}
```

#### API

```sh
jq -n --arg value "$PROVIDER_TOKEN" \
  '{name:"n8n_mcp_token",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/mcp-server?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @n8n-server.json
```

#### CLI

```sh
jq -n --arg value "$PROVIDER_TOKEN" \
  '{name:"n8n_mcp_token",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json

vf mcp-server create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < n8n-server.json
```

The Secret default supplies design-time discovery and also writes Main's Published value. Use a test project and set the selected Environment's Draft override when different. Keep `mcpServer.id` as `SERVER_ID`. Registration does not attach an action. Discover its actual tools and input contract:

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&serverID=$SERVER_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Select the approved tool from `mcpTools` and save its `id` as `MCP_TOOL_ID`:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$MCP_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf mcp-tool list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --server-id "$SERVER_ID" --output-format json
```

Select the approved tool from `mcpTools` and save its `id` as `MCP_TOOL_ID`:

```sh
vf mcp-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$MCP_TOOL_ID" --output-format json
```

Use `inputSchema` to prepare `inputs`; names, nesting and required fields come from this server, not a universal provider action schema. For this n8n recipe, define the workflow tool with one string input named `payload`; it contains the encoded request described below.

Save a test execution body as `n8n-inputs.json`. Use the encoder to prepare `n8n-payload.txt`, then run `jq -n --rawfile payload n8n-payload.txt '{inputs:{payload:$payload}}' > n8n-inputs.json`.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$MCP_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @n8n-inputs.json
```

#### CLI

```sh
vf mcp-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$MCP_TOOL_ID" --output-format json < n8n-inputs.json
```

Require `success: true`, inspect `output` and reject provider `isError` results. Output can contain text blocks and/or structured content; use the tool's actual business response rather than assuming an app record always appears at a fixed path. A successful MCP call can still return "not found" or pending work. Do not treat `truncated: true` as a complete result.

Create the agent attachment after the standalone test. Create the empty `n8n_request` project variable, then have the authenticated backend populate it on the next runtime action before the tool runs.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"n8n_request","color":"#515A63","defaultValue":""}'
```

#### CLI

```sh
vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name n8n_request --color-param '#515A63' --default-value '""' --output-format json
```

Save the following as `n8n-attachment.json` and substitute the discovered tool ID:

```json
{
  "type": "mcp",
  "mcpToolID": "YOUR_MCP_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Use for: Where is my order?. Use only the current successful result; explain missing data, failure or pending work without claiming completion. Never automatically repeat a write after an ambiguous outcome.",
  "inputVariables": {
    "payload": {
      "mcpIntegrationVariableName": "payload",
      "required": false,
      "defaultValue": "{n8n_request}"
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @n8n-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < n8n-attachment.json
```

Test from a client bound to this project's Draft: ask **Where is my order?**, inspect the tool call with the intended inputs, and compare its current result and the agent's answer with the provider history. Test a missing result/provider error; the agent must not claim success or reuse an older response. Creating a server or executing a tool alone does not prove this conversation path.

<a id="maintaining-the-connection"></a>

## Maintaining the connection

Inspect provider execution, update credentials and test the intended deployment.

| Symptom | Check |
| --- | --- |
| 404 | Use the production URL and publish the workflow; a test listener is temporary. |
| 401/403 | Use the credential configured on this trigger, not an n8n administrative API key. |
| Only “Workflow got started” | The Webhook responds immediately. Select the intended response mode and return the business result. |
| MCP tools missing | Attach tool nodes to MCP Server Trigger and publish any selected sub-workflow. |
| Broken MCP connections behind a proxy | Configure the proxy for the transport and route MCP connections consistently; see the provider's queue-mode guidance. |
| Timeout or partial write | Inspect Executions and the destination record before retrying. |

### Replace a credential

### 1. Inspect the original provider execution

Use the request ID and execution time to find the provider run and its downstream record. A timeout can follow a completed side effect; reconcile that state before repeating a write.

### 2. Update the intended credential version

#### Studio

Open the same project and **More → Secrets**, select the provider Secret and update the target Environment's **Draft value** for testing. After validation, explicitly set the Published value for the intended Environment; this changes the credential serving live traffic.

#### Developer

Retain `secret.id` from creation as `SECRET_ID`, set `PROVIDER_CREDENTIAL` to the replacement and use the value operation below. For n8n, choose the Secret for the selected MCP or Webhook connection. After validation, explicitly set the Published value for the intended Environment; this changes the credential serving live traffic.

#### Developer

Save the Draft update body as `credential-value.json`:

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' > credential-value.json
```

#### API

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @credential-value.json
```

#### CLI

```sh
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" \
  --output-format json < credential-value.json
```

For the selected Environment's Published credential, change `versionVariant` to `published` after the Draft test. To replace the project default used for MCP discovery, omit `environmentAlias` and `versionVariant`; this also writes Main's Published value. Test the intended connection before changing a live default.

Before launch, select the target Environment and supply the provider Secret's **Default value** for its published agent; a Draft override alone does not supply Published. [Publish the tested configuration](/docs/documentation/deploy/environments/publishing), then repeat the conversation test against that Environment's published client and verify the provider account/resource it reaches.

Rotate the credential with the provider owner, update the relevant Secret default/Environment overrides, and retest the existing tool. Removing a tool from Voiceflow does not remove the provider deployment or revoke its credential. Disable/revoke access in n8n when retiring the integration, then remove the unused attachment and API resource.
