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

# Create new integration

> Connect Voiceflow to a platform without a provider guide using API tools, MCP, Knowledge or human agent hand-off.

Use this guide when your platform does not have a page in the [integration catalog](/docs/guides/integrations/overview). If a provider guide exists, start there: it contains the account setup, mappings and checks for that platform.

## Before you begin

- Choose one task to connect, such as looking up an order, answering from approved articles or connecting a support teammate.
- Have a Voiceflow project you can edit and a test account in the external system. Obtain that system's API or hosted MCP documentation and the permissions for your task.
- Use a dedicated test project for initial credentials. Creating or changing a Secret's default also updates Main's Published value; a named Environment's Draft value is separate from its Published value.
- For customer records, have your application verify the customer and supply their record ID. A token authorizes the system connection; it does not establish the customer's identity.
- For human support, have a developer who can build and host the connection service and a teammate who can test replies.

#### Studio

Open your project in [Agent studio](https://creator.voiceflow.com). The instructions below use its tool editor, Knowledge base and Handoff settings.

#### Developer

Use your backend with a [Voiceflow API credential](/docs/api-reference/authentication), project ID and test Environment. Tool management uses your Voiceflow bearer token; the public Knowledge API below uses a separate project API key. Keep provider credentials on your backend or in [Secrets](/docs/documentation/build/data/secrets). The linked API and CLI references define the exact request shapes and commands.

## Choose the connection for your task

| You want the agent to… | Use | What you prepare |
| --- | --- | --- |
| Read or update records during a conversation | [API tools or MCP tools](#connect-data-and-actions) | A documented endpoint or hosted MCP server, its authorization and the inputs the task needs. |
| Answer from articles, policies or other approved content | [Knowledge](#connect-knowledge) | Content Voiceflow can import, with permission to use it for this agent. |
| Exchange messages with a human support teammate | [Human agent hand-off](#connect-human-support) | A deployed connection service that handles both outgoing requests and incoming human replies. |

These connections can be used together. An action that reads an article does not import it into Knowledge; creating a support ticket does not establish live handoff.

### Connect data and actions

Choose **API tool** when you need to configure a specific HTTP request. Choose **MCP** when the platform exposes a hosted server with tools for the same task.

#### API tool

#### 1. Define and authorize the request

Take the method, URL, required headers and request body from the external system's API contract. Start with a read operation on a test record. Store the credential in a Secret; bind customer identifiers to values verified by your application.

#### 2. Create and test the tool

#### Studio

Open **Agent → Global tools → + → API**. Configure the request, then bind its credential input to the Secret. Supply the test record's ID, run the tool and inspect the returned status and body. The [API tool instructions](/docs/documentation/build/tools/api-tool) cover request and response configuration.

#### Developer

Use [Create API tool](/docs/api-reference/api-tool/create-api-tool) to save the request in your test Environment. Retain its ID, inspect its input schema and use [Execute API tool](/docs/api-reference/api-tool/execute-api-tool) with those inputs. Check the execution result and the provider's response body. The [API-tool CLI reference](/docs/cli/commands/api-tool) provides the command path for the same resources.

#### 3. Make it available to the agent

#### Studio

Keep the tool in **Global tools**, or add it to the relevant Playbook. Describe when to call it and which response fields to use. Run a conversation with the verified test identity and confirm the agent uses the returned record.

#### Developer

Use [Create tool](/docs/api-reference/tool/create-tool) to attach the saved API tool to the agent or Playbook. Read its input IDs before binding defaults; a saved API request alone is not an attachment. Run a conversation and confirm the correct tool and record were used.

#### MCP

#### 1. Prepare the server and its authorization

Obtain the hosted MCP URL and authorization requirements from the platform. For a Secret-backed header, prepare the project-default Secret used for discovery as well as the runtime value for your test Environment.

#### 2. Discover and test the tools

#### Studio

Open **Agent → Global tools → + → MCP → Create MCP tool**. Enter the server URL and required headers, then select **Add MCP server**. Inspect the discovered tools and their parameters. Select a read tool and test it with the verified record ID.

#### Developer

Use [Create MCP server](/docs/api-reference/mcp-server/create-mcp-server), retain its ID and [list MCP tools](/docs/api-reference/mcp-tool/list-mcp-tools) for that server. Inspect the selected tool's schema before supplying its inputs to [Execute MCP tool](/docs/api-reference/mcp-tool/execute-mcp-tool). A discovered tool can still fail if the provider credential lacks permission.

#### 3. Attach the selected tool

#### Studio

Add the tested tool to **Global tools** or the relevant Playbook. Set its input guidance and explain when it should run. Check the [MCP tool instructions](/docs/documentation/build/tools/mcp-tool), then run a conversation and inspect the tool result.

#### Developer

Attach the discovered MCP tool with [Create tool](/docs/api-reference/tool/create-tool), using its actual tool and input IDs. Set the input defaults for the selected record and run a conversation to verify the attachment. Use the [MCP-server CLI reference](/docs/cli/commands/mcp-server) when managing the connection through the CLI.

<a id="connect-knowledge" />

### Import help articles

#### 1. Prepare approved content

Ask the content owner for public article URLs or an approved text/file export. An API token for record operations does not automatically authorize a Knowledge import. Keep private customer records out of content intended for general answers.

#### 2. Import and check processing

#### Studio

Open **Knowledge base → Add data source**. Choose **URL**, **Plain text** or the matching file source, then import the approved material. Wait for processing to finish before testing retrieval.

#### Developer

Use [Create document](/docs/api-reference/kbpublicapidocument/create-document) with the approved URL or file and your **project API key**. Retain `data.documentID` and read its processing status with [Get document](/docs/api-reference/kbpublicapidocument/get-document), using that key and the same `projectEnvironmentIDOrAlias`. Wait for `data.status` to become `SUCCESS`; inspect an `ERROR` before retrying. Omitting the Environment can read a different document set.

#### 3. Verify an answer uses the source

Enable Knowledge for the agent, ask a question answered by the imported material and inspect the retrieved source and answer. Importing content is separate from configuring ongoing updates; agree who will refresh or replace it when the original changes.

<a id="connect-human-support" />

### Human agent hand-off

#### 1. Build the two-way connection service

Have a developer follow [Connect your support platform](/docs/developers/handoff/connect). The service opens a provider conversation, forwards customer messages, receives human replies and sends signed callbacks to Voiceflow. It must retain the customer/conversation mapping and exclude private notes and echoed messages. Start with text; enable files only after implementing delivery in both directions.

#### 2. Connect the service and route escalation

#### Studio

Obtain the deployed HTTPS URL, service authorization and separate callback signing secret from the developer. In your project, open **Integrations → Custom Handoff → Connect** and enter those values. Follow [Studio handoff setup](/docs/documentation/handoff/setup) to configure the Workflow, verified customer identity, context and Return/Fail paths.

Creator Integrations catalog containing the Custom Handoff connection — Open Integrations to connect the handoff service your developer has deployed.

#### Developer

Complete the [API configuration sequence](/docs/developers/handoff/connect#configure-voiceflow-through-the-api) to save the service credentials, create the escalation Workflow and register it with the agent. Configure your customer client using the [Chat handoff reference](/docs/api-reference/agent-runtime/chat/handoff). The exact **Custom Handoff** setting names this interface; it is not a separate tier of provider integration.

#### 3. Test with a support teammate

Use the actual customer channel. Escalate once, exchange a customer message and a human reply, then end support and check the configured return behavior. Test service failure separately. A saved connection or created ticket does not prove that replies reach the customer.

## Verify the integration

- **Data:** the agent reads the correct customer's record. For a write, confirm the intended change in the external system and read it back before reporting success.
- **Knowledge:** the answer uses the approved imported source, rather than relying only on a successful import status.
- **Human support:** messages arrive once in both directions, private notes remain private, and the final reply arrives before the connection closes.
- **Published use:** prepare credentials for the target Published version, [publish the tested Environment](/docs/documentation/deploy/environments/publishing) and repeat the check in a fresh customer session. Draft execution alone does not verify the published agent.

### Troubleshoot a connection that saves but does not work

Check authorization, execution and delivery at the stage that failed.

1. **Request fails:** check the provider host, permission scopes, required inputs and the credential value used by the selected Environment.
2. **Tool is not called:** confirm it is attached to the agent or Playbook, its trigger describes the request, and the customer inputs are populated before execution.
3. **Knowledge is missing:** check processing status and test retrieval from the approved document.
4. **Human replies are missing:** inspect the provider receiver, stored conversation mapping, signed callback response and customer-client handling using the [handoff troubleshooting guide](/docs/documentation/handoff/troubleshooting).
