Build with

Overview

Voiceflow integrates with Zapier through two distinct jobs: call a configured app action through Zapier MCP and use its returned result, or send a webhook to start an existing Zap. Zapier owns the connected accounts and workflow execution. An MCP tool result and a webhook acknowledgment have different completion meanings.

Examples of when to use Zapier

The MCP setup below uses a server connection token with managed mode. Only configured, authorized tools are in scope; Voiceflow does not automatically gain every Zapier action or manage the server’s app connections.

Use connected app actions

Connect a managed MCP server and give the agent a scoped action.

Invoke the approved return-policy search when the customer asks to find the approved return policy. Zapier fixes the connected account and approved source; the agent collects only the search fields exposed by that action’s actual schema. Use the current successful result to answer. If it is missing, pending or an error, explain that state without claiming completion or reusing an earlier result.

Studio

1

Prepare the provider tools

At Zapier MCP, select Add MCP server → Other. Use managed mode, which exposes one tool per action, and configure only the approved actions and app connections. New servers can default to agentic mode, whose discovery/management meta-tools are a different interface. In the server’s Settings → API token, select Generate token and store the token immediately. Use the separate Token value with the endpoint https://mcp.zapier.com/api/v1/connect; keep it out of the URL. This token can execute the server’s tools, not just read its catalog. See connection-token setup and server modes.

2

Store the connection credential

In your test project in Agent studio, open More → Secrets and create zapier_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 Zapier, use https://mcp.zapier.com/api/v1/connect, and add Authorization with Bearer {zapier_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.

Connect the hosted Zapier server with its authorization header. Photo:
4

Configure invocation and inputs

Open the attached tool and write a Trigger for Find the approved return policy. In Zapier, fix the approved app connection and destination in the action configuration. In Voiceflow, describe only the remaining customer-supplied search inputs from the discovered schema. Do not let the model choose a credential, destination account or another customer identity.

5

Test a real conversation path

In the isolated project’s Run, ask Find the approved return policy. Use a known question whose approved answer exists in the configured source. 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.

Code

Set VF_TOKEN to your Voiceflow API credential, PROJECT_ID to the test project and ENVIRONMENT to its test alias. Set PROVIDER_TOKEN to the token prepared below. The current CLI reads VF_TOKEN.

At Zapier MCP, select Add MCP server → Other. Use managed mode, which exposes one tool per action, and configure only the approved actions and app connections. New servers can default to agentic mode, whose discovery/management meta-tools are a different interface. In the server’s Settings → API token, select Generate token and store the token immediately. Use the separate Token value with the endpoint https://mcp.zapier.com/api/v1/connect; keep it out of the URL. This token can execute the server’s tools, not just read its catalog. See connection-token setup and server modes.

Save this as zapier-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:

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

Use inputSchema to prepare inputs; names, nesting and required fields come from this server, not a universal provider action schema. Choose a read-only search action against approved support content for the first test. Fix its account and destination in Zapier before exposing it.

Save a test execution body as zapier-inputs.json. Its shape is {"inputs":{...}}, where ... is replaced by the actual schema-valid test values. This is a schema-first placeholder, not a copyable Zapier action signature. For this first test, use the fixed search phrase approved return policy in the schema’s search field. Standalone execution interprets Secret-name tokens in top-level strings; a backslash does not escape them. Do not use arbitrary customer text containing braces for this test, and do not change a string to an object unless the discovered schema permits that type.

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. Save the following as zapier-attachment.json and substitute the discovered tool ID:

For Zapier, add each exposed input that needs a fixed default under inputVariables: use its exact schema name, mcpIntegrationVariableName with that same name, required: false and the verified defaultValue. Leave only approved customer-supplied search fields model-collected. The provider action configuration must already fix its account and destination.

Test from a client bound to this project’s Draft: ask Find the approved return policy, 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.

Start a Zap

Send a confirmed request while keeping background completion separate.

Invoke Start support follow-up after the customer confirms the follow-up request. The authenticated application supplies the verified customer and confirmed reason as the prepared zapier_request variable; the webhook URL comes from its Secret default. Use the current successful acknowledgment to say submitted for processing. A failure or unconfirmed response must not become a completed-task claim or an automatic repeat submission.

Use this for an existing multi-step Zap that records work or sends a later notification. Catch Hook returns an acknowledgment that cannot be customized; it is not the downstream action’s final response. An off/deleted Zap can briefly still acknowledge requests before its disabled state propagates. See Zapier webhook triggers.

Prepare the receiving Zap

Ask the Zap owner to create Webhooks by Zapier → Catch Hook, copy its webhook URL, provide a test request and map the parsed fields to the existing approved workflow. The owner must deduplicate a stable request ID before writes, validate customer access and confirm the final result in Zap History and the destination system. Publish/turn on the Zap before using it beyond the trigger test. The webhook URL is the credential for this path; it is separate from the MCP token.

The developer supplies a literal-safe JSON string with request_id, verified customer_id and confirmed reason. Use encode-request.mjs, populate zapier_request on the next authenticated runtime action and bind it to the request tool. The Zap owns its downstream notification; sending the webhook does not automatically resume a Voiceflow conversation.

Configure and invoke the webhook tool

Studio

1

Store the webhook and prepared input

In the test project, create restricted Secret zapier_webhook_url in More → Secrets with the full Catch Hook URL. Create zapier_request in More → Variables with an empty default. For Run, temporarily use the developer’s prepared fictional test payload as the variable default; clear it afterward.

2

Create the API tool

Open Agent → Global tools → + → API, name it Start support follow-up, choose POST and set URL input {webhook_url}. Add Content-Type: application/json and raw JSON body {payload}. Bind webhook_url to Secret zapier_webhook_url and payload to variable zapier_request; neither should be model-collected. Keep Async execution off to inspect the acknowledgment.

Keep the Catch Hook URL and prepared request bound to trusted values. Photo:
3

Set the trigger and test the outcome

Set Trigger to run after the customer confirms a follow-up request. In Run, ask “Please send this issue for follow-up”, confirm its reason and inspect the call. The agent should say the request was submitted for processing, then the Zap owner checks the matched History run and final destination. Test a disabled/malformed request: an HTTP response alone must not become a completed-task claim.

Code

Set VF_TOKEN, PROJECT_ID and ENVIRONMENT for the test project. Set PROVIDER_CREDENTIAL to the Catch Hook URL supplied by the Zap owner. Keep that full URL in the Secret, not the tool definition.

Save this definition as zapier-webhook.json. Braced names declare inputs on this API tool; they are bound to Secrets/variables on its attachment later.

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

Creating the Secret default also writes Main’s Published value. If your selected Environment uses a different credential, set its Draft override before testing. Match each variables[].name to its id for the attachment; resolve unresolvedReferences before continuing.

Save the confirmed test request as zapier-request.json and download encode-request.mjs:

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.

Require success: true, a current 2xx output.status and no truncation. output.body is Zapier’s acknowledgment; verify the matched Zap run and its final destination separately.

Save this as zapier-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.

Your authenticated backend supplies the encoded string as variables.zapier_request on the next runtime action. Test Please send this issue for follow-up from a Draft client. Inspect the emitted tool call, current acknowledgment and agent response, then reconcile Zap History with the destination record. Test a rejected request/provider failure: the agent must not claim downstream completion or reuse an earlier result.

Maintaining the connection

Refresh the right credential and inspect the original provider run.

1

Repair the correct connection

For MCP, inspect the server’s History and its connected app authorization. A valid server token does not repair an expired app connection. For Catch Hook, inspect Zap History and whether the Zap is on. Fix the failing app action before replaying work.

2

Rotate and refresh deliberately

In Zapier MCP → Settings → API token, rotating a token immediately invalidates the old one. Update zapier_mcp_token in the Voiceflow project’s More → Secrets, including the relevant Environment’s Draft/Published values. For changed MCP actions, refresh the server in Settings → MCP servers or use vf mcp-server sync --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --server-id "$SERVER_ID"; inspect the refreshed tool schema and update existing attachments. A new action is not automatically an approved agent capability.

Code

Retain the created Secret’s secret.id as SECRET_ID. Use PROVIDER_CREDENTIAL for the replacement token or full Catch Hook URL. Choose zapier_mcp_token for MCP token rotation and zapier_webhook_url only when the Zap owner supplies a replacement hook. Updating one does not change the other.

Code

Save the Draft update body as 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.

3

Reconcile before retrying and launching

Check the original request/record before retrying a write after a timeout or partial Zap failure. Keep the same deduplication key for the same request. Set the target Environment’s Published Secret values, publish the tested agent and repeat the successful/failure conversation checks from its published client. Removing the Voiceflow tool does not revoke Zapier’s app connections or stop a running Zap.

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