updated chat/mcp docs (VapiAI#524)

Author: ramsrib

fern/chat/quickstart.mdx

@@ -162,7 +162,48 @@ We'll create a customer support chat for "TechFlow", a software company that wan
 
 ---
 
-## 5. Integrate with TypeScript
+## 5. Pass Dynamic Variables
+
+<Steps>
+  <Step title="Configure variables in your assistant">
+    In your assistant's system prompt, you can reference dynamic variables using `{{variableName}}` syntax:
+    
+    ```txt title="System Prompt with Variables"
+    You are a helpful customer support agent for {{companyName}}.
+    
+    Your role:
+    - Answer questions about {{companyName}}'s products
+    - Help customers with their {{serviceType}} needs
+    - Escalate to human agents when needed
+    
+    Current customer tier: {{customerTier}}
+    ```
+  </Step>
+  <Step title="Pass variables in your chat request">
+    Use `assistantOverrides.variableValues` to pass dynamic data:
+    
+    ```bash title="Chat Request with Variables"
+    curl -X POST https://api.vapi.ai/chat \
+      -H "Authorization: Bearer YOUR_API_KEY" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "assistantId": "your-assistant-id",
+        "input": "I need help with my account",
+        "assistantOverrides": {
+          "variableValues": {
+            "companyName": "TechFlow Solutions",
+            "serviceType": "software",
+            "customerTier": "Premium"
+          }
+        }
+      }'
+    ```
+  </Step>
+</Steps>
+
+---
+
+## 6. Integrate with TypeScript
 
 <Steps>
   <Step title="Create a simple chat function">
@@ -236,7 +277,9 @@ We'll create a customer support chat for "TechFlow", a software company that wan
 
 ---
 
-## 6. Test Your Chat Bot
+
+
+## 7. Test Your Chat Bot
 
 <Steps>
   <Step title="Test various scenarios">
@@ -267,6 +310,14 @@ We'll create a customer support chat for "TechFlow", a software company that wan
   </Step>
 </Steps>
 
+## Limitations
+
+<Note>
+**Current chat functionality limitations:**
+- "Query" tool for knowledge-base searches is not yet supported
+- Server webhook events (status updates, end-of-call reports, etc.) are not supported
+</Note>
+
 ## Next Steps
 
 Take your chat bot to the next level:

fern/sdk/mcp-server.mdx

@@ -414,10 +414,16 @@ async function main() {
           assistantId: assistantId,
           phoneNumberId: phoneNumberId,
           customer: {
-            phoneNumber: "+1234567890"  // Replace with actual customer phone number
+            number: "+1234567890"  // Replace with actual customer phone number
           }
           // Optional: schedule a call for the future
           // scheduledAt: "2025-04-15T15:30:00Z"
+          // assistantOverrides: {
+          //  variableValues: {
+          //   name: 'John Doe',
+          //   age: '25',
+          //  },
+          // },
         },
       });
       const createdCall = parseToolResponse(createCallResponse);

fern/tools/mcp.mdx

@@ -66,7 +66,7 @@ Now, add the MCP tool to your assistant:
 
 The MCP integration follows these steps during a call:
 
-1. When a call starts, Vapi connects to your configured MCP server
+1. When a call starts, Vapi connects to your configured MCP server using **Streamable HTTP** protocol by default
 2. The MCP server returns a list of available tools and their capabilities
 3. These tools are dynamically added to your assistant's available tools
 4. The assistant can then use these tools during the call
@@ -81,13 +81,29 @@ The MCP integration follows these steps during a call:
   The tools available through MCP are determined by your MCP server provider. Different providers may offer different sets of tools.
 </Note>
 
+### Request Headers
+
+MCP requests from Vapi include identifying headers to help with context and debugging:
+
+- **`X-Call-Id`**: Included in requests during voice calls to identify the specific call
+- **`X-Chat-Id`**: Included in requests during chat interactions to identify the specific chat
+- **`X-Session-Id`**: Included in requests during chat interaction if the chat is part of a session
+
 ## Tool Configuration
 
 ### MCP Tool
 
-This tool uses the following field to connect to your MCP server:
+This tool uses the following configuration options:
+
+**Required:**
+- `server.url`: The URL of your MCP server (e.g., https://actions.zapier.com/mcp/actions/)
 
-- `serverUrl`: The URL of your MCP server (e.g., https://actions.zapier.com/mcp/actions/)
+**Optional:**
+- `server.headers`: Custom headers to include in requests to the MCP server
+- `metadata`: Additional configuration options for the MCP connection
+  - `protocol`: Communication protocol to use. Options are:
+    - `"shttp"` (default): Uses Streamable HTTP protocol
+    - `"sse"`: (deprecated) Uses Server-Sent Events protocol
 
 <Note>
   The server URL should be treated as a credential and kept secure. It will be used to authenticate requests to the MCP server.
@@ -97,6 +113,8 @@ This tool uses the following field to connect to your MCP server:
 
 Here's how the MCP tool can be used in your assistant's configuration:
 
+### Default Configuration (Streamable HTTP)
+
 ```json
 {
   "model": {
@@ -111,7 +129,9 @@ Here's how the MCP tool can be used in your assistant's configuration:
     "tools": [
       {
         "type": "mcp",
-        "name": "mcpTools",
+        "function": {
+          "name": "mcpTools"
+        },
         "server": {
             "url": "https://actions.zapier.com/mcp/actions/"
         }
@@ -121,13 +141,51 @@ Here's how the MCP tool can be used in your assistant's configuration:
 }
 ```
 
+### Custom Configuration (SSE Protocol)
+
+If you need to use Server-Sent Events protocol instead:
+
+```json
+{
+  "model": {
+    "provider": "openai",
+    "model": "gpt-4",
+    "messages": [
+      {
+        "role": "system",
+        "content": "You are a helpful personal assistant named Alex..."
+      }
+    ],
+    "tools": [
+      {
+        "type": "mcp",
+        "function": {
+          "name": "mcpTools"
+        },
+        "server": {
+            "url": "https://actions.zapier.com/mcp/actions/",
+            "headers": {
+              "Authorization": "Bearer your-token",
+              "X-Custom-Header": "your-value"
+            }
+        },
+        "metadata": {
+          "protocol": "sse"
+        }
+      }
+    ]
+  }
+}
+```
+
 ## Best Practices
 
-1. **Dynamic Tool Awareness**: Be aware that the available tools may change between calls
-2. **Clear Instructions**: Provide clear instructions in your assistant's system message about how to handle dynamic tools
-3. **Error Handling**: Include fallback responses for cases where tools fail or are unavailable
-4. **User Communication**: Explain to users what tools you're using and what actions you're taking
-5. **Security**: Treat the MCP server URL as a credential and keep it secure
+1. **Protocol Selection**: Use the default Streamable HTTP protocol for better performance unless you specifically need SSE
+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
+5. **User Communication**: Explain to users what tools you're using and what actions you're taking
+6. **Security**: Treat the MCP server URL as a credential and keep it secure
 
 ## Example MCP Providers