diff --git a/fern/docs.yml b/fern/docs.yml index 3ac5d83c4..8ce1835a1 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -286,6 +286,9 @@ navigation: path: tools/integrations.mdx icon: fa-light fa-cubes contents: + - page: Make + path: tools/integrations/make.mdx + icon: fa-light fa-diagram-project - page: Google Calendar path: tools/google-calendar.mdx icon: fa-light fa-calendar-days diff --git a/fern/tools/custom-tools.mdx b/fern/tools/custom-tools.mdx index acd4c3583..6cde4dd71 100644 --- a/fern/tools/custom-tools.mdx +++ b/fern/tools/custom-tools.mdx @@ -125,7 +125,7 @@ Custom function tools are not the only tool type where you can define an LLM-fac | `function` (custom) | Yes — the entire purpose of this tool type. | | `apiRequest` | Yes — drives both the LLM-supplied arguments and the request body construction. | | `handoff` | Yes — fills handoff-time arguments inline. See [Approach 1 in the squads guide](/squads/passing-data-between-assistants#approach-1-handoff-arguments). | -| `transferCall`, `endCall`, `dtmf`, `voicemail`, `sms`, `slack-send-message`, GHL/Google integrations, `mcp`, `make`, Anthropic-native (`bash`, `computer`, `textEditor`) | No — the schema is Vapi-controlled or auto-derived from the underlying integration; you do not define it directly. | +| `transferCall`, `endCall`, `dtmf`, `voicemail`, `sms`, `slack-send-message`, GHL/Google integrations, `mcp`, Anthropic-native (`bash`, `computer`, `textEditor`) | No — the schema is Vapi-controlled or auto-derived from the underlying integration; you do not define it directly. | For tool types that accept customer-defined `function.parameters`, you can also pair them with **static parameters** -- a separate top-level `parameters` array on the tool that merges server-trusted values into the body without the LLM ever seeing them. See [Static variables and aliases](/tools/static-variables-and-aliases) for the full pattern, including when to use static parameters as a security boundary. diff --git a/fern/tools/integrations.mdx b/fern/tools/integrations.mdx index 2ebc63fa6..8e4ea9bf6 100644 --- a/fern/tools/integrations.mdx +++ b/fern/tools/integrations.mdx @@ -1,17 +1,20 @@ --- title: Integrations -subtitle: Connect an assistant to an external service with a prebuilt tool -description: Connect a Vapi assistant to Google Calendar, Google Sheets, Slack, or GoHighLevel using prebuilt integration tools that need no server of your own. +subtitle: Connect an assistant to external services with prebuilt tools or standard tool patterns +description: Connect a Vapi assistant to external services using prebuilt integrations or service guides for API Request, Model Context Protocol (MCP), and Function tools. slug: tools/integrations --- -Integration tools connect an assistant to a specific external service. Unlike a [Function tool](/tools/custom-tools), which calls a server you build and host, an integration tool is prebuilt: you connect the account once, configure what the tool is allowed to do, and add it to an assistant. +Vapi can connect an assistant to an external service through a prebuilt integration or a standard tool such as [API Request](/tools/api-request), [Model Context Protocol (MCP)](/tools/mcp), or [Function](/tools/custom-tools). -Each integration below covers one service. The pages follow the same shape: what the integration does, how to connect the account, the tool's configuration options, and an example of the assistant using it during a call. +Use the service guides below to choose the appropriate connection pattern and configure the integration. ## Available integrations + + Connect Make through an API Request, MCP, or Function tool, depending on the data and context the scenario needs. + Create calendar events and check availability so an assistant can schedule appointments on a call. diff --git a/fern/tools/integrations/make.mdx b/fern/tools/integrations/make.mdx new file mode 100644 index 000000000..8749239ea --- /dev/null +++ b/fern/tools/integrations/make.mdx @@ -0,0 +1,41 @@ +--- +title: Choose a Make integration pattern +subtitle: Compare Vapi tool patterns for connecting an assistant to Make +description: "Choose a Make integration pattern for an assistant: API Request for webhooks, Model Context Protocol (MCP) for discovered tools, or Function for call context." +slug: tools/integrations/make +--- + +Connect a Vapi assistant to Make to invoke scenarios that coordinate actions and data across apps configured in Make. Use this guide to choose among Vapi's general-purpose API Request, Model Context Protocol (MCP), and Function tools. Start with an **API Request tool** unless the scenario needs dynamic tool discovery or Vapi's `tool-calls` webhook protocol. + +## Choose a pattern + +| What the Make scenario needs | Use | Why | +| --- | --- | --- | +| An ordinary webhook that accepts and returns JSON | **[API Request tool](/tools/api-request)** | Vapi sends the configured HTTP request directly and gives the JSON response to the assistant. This is the recommended default. | +| A curated tool surface that Make owns and Vapi discovers at runtime | **[MCP tool](/tools/mcp)** | Make exposes eligible scenarios as MCP tools and Vapi imports the tools exposed by that server. | +| Vapi's `tool-calls` envelope or call, assistant, and artifact context | **[Function tool](/tools/custom-tools)** | Vapi sends its webhook payload to the scenario, which must return the expected Function-tool response. | +| Asynchronous execution or server-driven [Live Call Control](/calls/call-features) | **[Function tool](/tools/custom-tools)** | Function tools support asynchronous execution, and their webhook payload includes the call context needed for live control. | + +## API Request + +Use an API Request tool when Make exposes a webhook that accepts a JSON request and returns a JSON response. If the assistant needs the scenario's result, the Make webhook must return JSON in the request-response flow. Make does not need to parse or construct a Vapi-specific webhook envelope. + +This pattern has the smallest integration contract and is the best starting point for most Make scenarios. + +## MCP + +Use MCP when Make should define the tool surface. Make exposes active, on-demand scenarios as tools. Vapi imports every tool exposed by the configured MCP server; Vapi does not apply a separate per-tool filter. + +Configure the Make MCP token with least-privilege scopes. Use Make's [scenarios as tools access control](https://developers.make.com/mcp-server/connect-using-mcp-token/scenarios-as-tools-access-control) to expose only the scenarios the assistant needs. See [Make MCP Server](https://developers.make.com/mcp-server) for Make's current connection documentation. + +## Function + +Use a Function tool when the Make scenario must receive Vapi's `tool-calls` message, including call, assistant, or artifact context. This is also the appropriate pattern for asynchronous execution or live-call actions. + +The scenario must parse Vapi's webhook payload and return the [Function tool response](/tools/custom-tools#server-response-format-providing-results-and-context) for synchronous calls. This extra protocol work is unnecessary for an ordinary JSON webhook, so prefer API Request in that case. + +## Runnable examples + + + Run the API Request and MCP examples and inspect the complete Vapi → Make → Vapi round trip. + diff --git a/fern/tools/introduction.mdx b/fern/tools/introduction.mdx index 19782cdcb..45f44667c 100644 --- a/fern/tools/introduction.mdx +++ b/fern/tools/introduction.mdx @@ -33,7 +33,7 @@ Because the model controls both *when* a tool runs and the arguments it receives | [Client-side tools](/tools/client-side-websdk) | Runs in the browser through the Web SDK, with no server URL | | [Query tool](/knowledge-base/using-query-tool) | Searches a [knowledge base](/knowledge-base) and returns matching content | | [MCP tools](/tools/mcp) | Connects to an MCP server so the assistant can use tools resolved at runtime | -| [Integrations](/tools/integrations) | Prebuilt connections to Google Calendar, Google Sheets, Slack, and GoHighLevel | +| [Integrations](/tools/integrations) | Service-specific guides for prebuilt integrations and standard tool patterns | If you are deciding between calling an API directly and running your own logic, see [When to use API Request or Function tools](/tools/api-request-vs-function). diff --git a/fern/tools/mcp.mdx b/fern/tools/mcp.mdx index b770bfd42..ccc7aef1c 100644 --- a/fern/tools/mcp.mdx +++ b/fern/tools/mcp.mdx @@ -37,7 +37,7 @@ First, you need to obtain an MCP server URL from your chosen provider: For Zapier MCP, visit https://mcp.zapier.com/mcp/?client=vapi? to generate your MCP server URL. This URL should be treated as a credential and kept secure. - To generate your Make MCP Server URL (also known as MCP Token), navigate to your Make profile > API Access tab > Tokens > Add token. See [Obtaining MCP Token documentation](https://developers.make.com/mcp-server/make-cloud-mcp-server/obtaining-mcp-token) for detailed instructions. This URL should be treated as a credential and kept secure. + For Make MCP, create an [MCP token](https://developers.make.com/mcp-server/connect-using-mcp-token) and construct the connection URL described in Make's documentation. Treat the token and any URL containing it as credentials. ### 2. Create and Configure MCP Tool @@ -49,7 +49,9 @@ After obtaining your MCP server URL, create and configure the tool: 3. Select **MCP** from the available options 4. Provide a name and description explaining when it should be invoked 5. Configure the tool with the following required field: - - `serverUrl`: The URL of your MCP server + - **Server URL**: The URL of your MCP server + +The Dashboard labels this field **Server URL**. In an API request, configure the same value as `server.url`. The MCP server URL should be treated as a credential and kept secure. It will be used to authenticate requests to the MCP server. @@ -84,9 +86,13 @@ The MCP integration follows these steps during a call or chat session: - The tools available through MCP are determined by your MCP server provider. Different providers may offer different sets of tools. + The tools available through MCP are determined by your MCP server provider. Vapi imports the complete tool list exposed by the configured server and does not apply its own per-tool filter. + + Expose only the tools the assistant needs. Large tool lists consume model context and can increase latency and timeout risk. Use the MCP provider's access controls and least-privilege credentials to keep the tool surface focused. + + ### Request Headers MCP requests from Vapi include identifying headers to help with context and debugging: @@ -186,7 +192,7 @@ If you need to use Server-Sent Events protocol instead: ## Best Practices -1. **Protocol Selection**: Use the default Streamable HTTP protocol for better performance unless you specifically need SSE +1. **Protocol Selection**: Use the default Streamable HTTP protocol. SSE is deprecated and should be used only when required by the server 2. **Dynamic Tool Awareness**: Be aware that the available tools may change between calls 3. **Clear Instructions**: Provide clear instructions in your assistant's system message about how to handle dynamic tools 4. **Error Handling**: Include fallback responses for cases where tools fail or are unavailable @@ -197,17 +203,35 @@ If you need to use Server-Sent Events protocol instead: ### Make MCP -The Make MCP Server provides access to the Make scenarios you select, allowing you to provision them as Custom Tools through MCP. - -1. Define your Make scenarios, configuring scenario [inputs and outputs](https://help.make.com/scenario-inputs-and-outputs) and setting them to be [scheduled on demand](https://help.make.com/schedule-a-scenario#30pY_) -2. Get your [Make MCP Token](https://developers.make.com/mcp-server/make-cloud-mcp-server/obtaining-mcp-token) -3. Choose your MCP [Tool Access Control](https://developers.make.com/mcp-server/make-cloud-mcp-server/tool-access-control) mechanism and define your MCP URL -4. Add the URL to your Vapi MCP tool configuration -5. Your assistant will now have access to your chosen Make scenarios - - - Make Cloud MCP allows you to build simple or complex Custom Tools using business logic to access the most important apps in your business tech stack. Check the full list in the Make app gallery. - +Make MCP can expose active, on-demand scenarios as tools and can expose account-management tools when the token has the corresponding scopes. + + + + Define the inputs and outputs for each scenario, then set its schedule to **On demand**. + + + Create a [Make MCP token](https://developers.make.com/mcp-server/connect-using-mcp-token) with the minimum scopes required. + + + Use Make's [scenarios as tools access control](https://developers.make.com/mcp-server/connect-using-mcp-token/scenarios-as-tools-access-control) to expose only the scenarios the assistant needs. + + + Add the resulting URL as the Vapi MCP tool's **Server URL** in the Dashboard, or as `server.url` through the API. + + + Keep **Streamable HTTP** selected. + + + + + Scenario access-control parameters apply to scenario tools, not management tools. A broadly scoped token can expose management tools capable of modifying Make resources. Because Vapi imports every exposed tool, broad access also increases model context, latency, and timeout risk. Grant no management scopes unless the assistant needs them. + + + + Provision a demo scenario, inspect the tools Make exposes, and verify the Vapi → Make → Vapi round trip. + + +See [Connect Vapi to Make](/tools/integrations/make) to compare MCP with API Request and Function tools. ### Zapier MCP @@ -230,7 +254,7 @@ Composio also offers an MCP server for integration: 2. Select the tool you want to integrate (e.g., Gmail) 3. Enable the MCP server for the selected tool by connecting your account using authentication flow 4. Create a server and copy the generated URL -5. Add this URL to your MCP tool configuration as the `serverUrl` +5. Add this URL as the **Server URL** in the Dashboard, or as `server.url` through the API 6. Your assistant will now have access to the specific Composio tool integration diff --git a/fern/tools/static-variables-and-aliases/static-parameters.mdx b/fern/tools/static-variables-and-aliases/static-parameters.mdx index ddcf32197..2f617390a 100644 --- a/fern/tools/static-variables-and-aliases/static-parameters.mdx +++ b/fern/tools/static-variables-and-aliases/static-parameters.mdx @@ -26,7 +26,7 @@ The `parameters` field lets you define key-value pairs that are always merged in | `apiRequest` | Yes | | `function` (modern, under `assistant.model.tools[]`) | Yes | | `handoff` | No -- see [Forwarding trusted data across handoffs](/tools/static-variables-and-aliases/extract-and-chain#forwarding-trusted-data-across-handoffs) | -| All other tool types (`transferCall`, `dtmf`, `endCall`, `voicemail`, `sms`, `slack-send-message`, GHL/Google integrations, MCP, query, output, sipRequest, makeTool, bash/computer/textEditor) | No | +| All other tool types (`transferCall`, `dtmf`, `endCall`, `voicemail`, `sms`, `slack-send-message`, GHL/Google integrations, MCP, query, output, sipRequest, bash/computer/textEditor) | No | **Legacy `assistant.model.functions[]` does NOT support static parameters.** If you are still defining tools via the deprecated `assistant.model.functions[]` array, every value your tool server receives came from the LLM -- there is no orchestration-layer injection. Migrate to `assistant.model.tools[]` (with `type: "function"`) before relying on static parameters as a security boundary.