> ## Documentation Index
> Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to MCP Servers for Pre-Built Tools

> Connect Model Context Protocol servers to expand your agent's capabilities with pre-built tools and external data sources.

Connect your agent to MCP servers for pre-built tool integrations. Instead of writing custom webhooks, you plug into standardized servers that expose databases, calendars, CRMs, and other systems.

**What you'll learn:** How MCP works, configuring connections, authentication options, tool filtering, and when to use MCP vs custom webhooks.

<Note>
  Think of MCP as a "USB-C port for AI applications" — a universal way to connect AI agents to external systems.
</Note>

## Overview

MCP standardizes how AI agents interact with external tools. Instead of building custom integrations for each system, MCP provides a unified interface.

**Key benefits:**

* One protocol for all tool integrations
* Automatic tool discovery from MCP servers
* Standardized authentication and error handling
* Growing ecosystem of pre-built MCP servers

***

<Accordion title="How MCP works">
  ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
  sequenceDiagram
      participant Agent as Your Agent
      participant Platform as Dasha BlackBox
      participant MCP as MCP Server
      participant External as External System

      Agent->>Platform: User requests data
      Platform->>MCP: Call tool via MCP
      MCP->>External: Execute operation
      External-->>MCP: Return result
      MCP-->>Platform: Return formatted data
      Platform-->>Agent: Present to user
  ```
</Accordion>

1. **Connection setup:** Configure your agent to connect to an MCP server
2. **Tool discovery:** Platform automatically discovers available tools
3. **Runtime invocation:** Agent calls tools during conversations
4. **Secure execution:** MCP server executes operations with authentication
5. **Result integration:** Tool results are incorporated into responses

***

## Set up MCP connections

<Tabs>
  <Tab title="Dashboard">
    Navigate to the **MCP Connections** tab when creating or editing an agent.

    <Steps>
      <Step title="Add new connection">
        Click **Add MCP Connection** to create a new connection.
      </Step>

      <Step title="Configure details">
        * **Name:** Descriptive identifier (e.g., "GitHub API", "Company Database")
        * **Server URL:** HTTP/HTTPS endpoint of your MCP server
        * **Description:** Optional notes about purpose
      </Step>

      <Step title="Set up authentication">
        Choose authentication method:

        * **No Authentication:** For public/internal servers
        * **API Key:** Include API key in custom header
        * **Bearer Token:** OAuth 2.0 or similar token-based auth
      </Step>

      <Step title="Select transport">
        * **SSE** (Server-Sent Events): For streaming connections (default)
        * **StreamableHTTP:** For HTTP-based request/response
      </Step>

      <Step title="Test connection">
        Click **Test Connection** to verify server is reachable and tools are discoverable.
      </Step>

      <Step title="Enable connection">
        Toggle the connection status to enable it. Only enabled connections are used at runtime.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const agent = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: "Customer Support Agent with CRM Access",
        config: {
          primaryLanguage: "en-US",
          llmConfig: {
            vendor: "openai",
            model: "gpt-4.1",
            prompt: "You are a customer support agent with CRM access..."
          },
          ttsConfig: {
            vendor: "ElevenLabs",
            voiceId: "zmcVlqmyk3Jpn5AVYcAL",
            model: "eleven_flash_v2_5"
          },
          mcpConnections: [
            {
              name: "Customer CRM",
              serverUrl: "https://mcp.example.com/crm",
              description: "Access to customer records",
              authentication: {
                type: "apiKey",
                headerName: "X-API-Key",
                apiKey: "YOUR_CRM_API_KEY"
              },
              transport: "StreamableHTTP",
              isEnabled: true,
              whiteListTools: [
                "get_customer_info",
                "get_order_history"
              ]
            }
          ]
        }
      })
    });
    ```
  </Tab>
</Tabs>

***

## Configuration reference

### Required fields

| Field       | Type         | Description                           |
| ----------- | ------------ | ------------------------------------- |
| `name`      | string       | Unique identifier for this connection |
| `serverUrl` | string (URL) | HTTP/HTTPS endpoint of the MCP server |

### Optional fields

| Field            | Type      | Default | Description                   |
| ---------------- | --------- | ------- | ----------------------------- |
| `description`    | string    | null    | Human-readable description    |
| `authentication` | object    | null    | Authentication configuration  |
| `customHeaders`  | object    | null    | Additional HTTP headers       |
| `isEnabled`      | boolean   | true    | Whether connection is active  |
| `transport`      | enum      | "SSE"   | `"SSE"` or `"StreamableHTTP"` |
| `whiteListTools` | string\[] | null    | Tools to include exclusively  |
| `blackListTools` | string\[] | null    | Tools to exclude              |

***

## Authentication types

<Accordion title="No authentication">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "authentication": {
      "type": "none"
    }
  }
  ```
</Accordion>

<Accordion title="API key">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "authentication": {
      "type": "apiKey",
      "headerName": "X-API-Key",
      "apiKey": "your-api-key-here"
    }
  }
  ```
</Accordion>

Common header names: `X-API-Key`, `X-Auth-Token`, `API-Key`

<Accordion title="Bearer token">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "authentication": {
      "type": "bearer",
      "token": "your-bearer-token-here"
    }
  }
  ```
</Accordion>

<Accordion title="Custom headers">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "customHeaders": {
      "X-Organization-ID": "org-12345",
      "X-Environment": "production"
    }
  }
  ```
</Accordion>

***

## Transport types

| Transport          | Connection  | Best for                        | Latency |
| ------------------ | ----------- | ------------------------------- | ------- |
| **SSE** (default)  | Persistent  | Real-time tools, streaming data | Lower   |
| **StreamableHTTP** | Per-request | REST APIs, batch operations     | Higher  |

**Choose SSE when:**

* Your MCP server supports SSE
* You need real-time tool responses
* Low latency is important

**Choose StreamableHTTP when:**

* Your MCP server doesn't support SSE
* You're integrating with REST-based implementations
* Tools are simple request/response operations

***

## Tool filtering

Control which MCP tools are available to your agent.

<Note>
  Tool whitelisting and blacklisting are currently available only through the API. The dashboard UI does not expose these options.
</Note>

<Accordion title="Whitelist tools">
  Include ONLY specified tools:

  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "whiteListTools": ["search", "calendar", "query_customers"]
  }
  ```
</Accordion>

<Accordion title="Blacklist tools">
  Exclude specific tools:

  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "blackListTools": ["admin_tool", "delete_customer", "export_database"]
  }
  ```
</Accordion>

### Precedence rules

<Warning>
  When both `whiteListTools` and `blackListTools` are specified, **whitelist takes precedence** and blacklist is ignored.
</Warning>

| Configuration  | Result                            |
| -------------- | --------------------------------- |
| Only whitelist | Only whitelisted tools available  |
| Only blacklist | All tools except blacklisted      |
| Both specified | Whitelist wins, blacklist ignored |
| Neither        | All discovered tools available    |

***

## Test connections

<Accordion title="Via API">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const result = await fetch('https://blackbox.dasha.ai/api/v1/mcp/verify', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Test Connection",
      serverUrl: "https://mcp.example.com/api",
      authentication: {
        type: "apiKey",
        headerName: "X-API-Key",
        apiKey: "test-key"
      },
      transport: "StreamableHTTP"
    })
  });

  const verification = await result.json();
  console.log('Connection status:', verification.success);
  // Output: true

  console.log('Tools found:', verification.availableTools.length);
  // Output: 5
  ```
</Accordion>

<Accordion title="Verification response">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "success": true,
    "message": "Connection successful",
    "availableTools": [
      {
        "name": "get_customer_info",
        "description": "Retrieve customer information by ID",
        "schema": { ... },
        "isEnabled": true
      }
    ],
    "responseTimeMs": 145.2
  }
  ```
</Accordion>

***

## Common use cases

<Accordion title="CRM integration">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "name": "Salesforce CRM",
    "serverUrl": "https://mcp.yourcompany.com/salesforce",
    "authentication": {
      "type": "bearer",
      "token": "YOUR_SALESFORCE_TOKEN"
    },
    "whiteListTools": [
      "get_customer_by_email",
      "get_open_cases",
      "create_case"
    ]
  }
  ```
</Accordion>

<Accordion title="Database access">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "name": "Analytics Database",
    "serverUrl": "https://mcp.yourcompany.com/postgres",
    "authentication": {
      "type": "apiKey",
      "headerName": "X-DB-Key",
      "apiKey": "YOUR_DB_API_KEY"
    },
    "whiteListTools": [
      "query_sales_data",
      "query_user_metrics"
    ]
  }
  ```
</Accordion>

<Accordion title="Knowledge base">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "name": "Knowledge Base",
    "serverUrl": "https://mcp.yourcompany.com/docs",
    "transport": "SSE",
    "authentication": {
      "type": "none"
    }
  }
  ```
</Accordion>

***

## MCP vs custom webhooks

| Feature        | MCP tools              | Custom webhooks         |
| -------------- | ---------------------- | ----------------------- |
| Setup          | Requires MCP server    | Direct webhook endpoint |
| Tool discovery | Automatic              | Manual configuration    |
| Authentication | Standardized           | Custom per endpoint     |
| Best for       | Multiple related tools | Single-purpose actions  |

**Use MCP when:**

* Multiple related tools from same system
* Dynamic tool discovery needed
* Standardized authentication

**Use custom webhooks when:**

* Single-purpose tool/action
* Legacy systems without MCP support
* Custom execution logic required

***

## Best practices

### Security

* Use whitelisting to expose only necessary tools
* Avoid granting access to destructive operations
* Always use authentication for production servers
* Rotate API keys regularly
* Use HTTPS for all MCP server URLs

### Performance

* Aim for under 500ms tool response times
* Use caching on MCP server for frequent data
* Consider async operations for long-running tasks

### Reliability

* Return descriptive error messages
* Implement retries for transient failures
* Monitor tool invocation success rates

***

## Troubleshooting

<Accordion title="Connection failures">
  * Verify `serverUrl` is correct and accessible
  * Check authentication credentials
  * Ensure MCP server is running
  * Verify network connectivity (firewalls, proxies)
</Accordion>

<Accordion title="Authentication errors (401/403)">
  * Verify authentication type matches server expectations
  * Check API key or token is not expired
  * Ensure `headerName` matches what server expects
  * Test authentication with curl or Postman
</Accordion>

<Accordion title="No tools discovered">
  * Verify MCP server implements tool listing correctly
  * Check `whiteListTools` isn't too restrictive
  * Ensure tools aren't disabled on server side
  * Check for server-side errors
</Accordion>

<Accordion title="Tool invocation failures">
  * Verify tool schemas match parameter requirements
  * Check external system is accessible
  * Monitor MCP server logs
  * Test tools independently outside conversation flow
</Accordion>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Tools & functions" icon="wrench" href="/docs/create/tools-and-functions">
    Configure custom webhook-based tools
  </Card>

  <Card title="Create Agent" icon="robot" href="/docs/create/creating-your-first-agent">
    Core agent configuration
  </Card>

  <Card title="Dashboard testing" icon="flask" href="/docs/test/dashboard-testing">
    Test MCP tools in conversations
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/docs/troubleshooting/common-issues">
    Debug tool invocation issues
  </Card>
</CardGroup>