Connect to MCP Servers for Pre-Built Tools - Dasha BlackBox Documentation

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.

Think of MCP as a “USB-C port for AI applications” — a universal way to connect AI agents to external systems.

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

How MCP works

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

Set up MCP connections

Dashboard
API

Navigate to the MCP Connections tab when creating or editing an agent.

Add new connection

Click Add MCP Connection to create a new connection.

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

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

Select transport

SSE (Server-Sent Events): For streaming connections (default)
StreamableHTTP: For HTTP-based request/response

Test connection

Click Test Connection to verify server is reachable and tools are discoverable.

Enable connection

Toggle the connection status to enable it. Only enabled connections are used at runtime.

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"
          ]
        }
      ]
    }
  })
});

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

No authentication

{
  "authentication": {
    "type": "none"
  }
}

API key

{
  "authentication": {
    "type": "apiKey",
    "headerName": "X-API-Key",
    "apiKey": "your-api-key-here"
  }
}

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

Bearer token

{
  "authentication": {
    "type": "bearer",
    "token": "your-bearer-token-here"
  }
}

Custom headers

{
  "customHeaders": {
    "X-Organization-ID": "org-12345",
    "X-Environment": "production"
  }
}

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.

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

Whitelist tools

Include ONLY specified tools:

{
  "whiteListTools": ["search", "calendar", "query_customers"]
}

Blacklist tools

Exclude specific tools:

{
  "blackListTools": ["admin_tool", "delete_customer", "export_database"]
}

Precedence rules

When both whiteListTools and blackListTools are specified, whitelist takes precedence and blacklist is ignored.

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

Via API

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

Verification response

{
  "success": true,
  "message": "Connection successful",
  "availableTools": [
    {
      "name": "get_customer_info",
      "description": "Retrieve customer information by ID",
      "schema": { ... },
      "isEnabled": true
    }
  ],
  "responseTimeMs": 145.2
}

Common use cases

CRM integration

{
  "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"
  ]
}

Database access

{
  "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"
  ]
}

Knowledge base

{
  "name": "Knowledge Base",
  "serverUrl": "https://mcp.yourcompany.com/docs",
  "transport": "SSE",
  "authentication": {
    "type": "none"
  }
}

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

Connection failures

Verify serverUrl is correct and accessible
Check authentication credentials
Ensure MCP server is running
Verify network connectivity (firewalls, proxies)

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

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

Tool invocation failures

Verify tool schemas match parameter requirements
Check external system is accessible
Monitor MCP server logs
Test tools independently outside conversation flow

Next steps

Tools & functions

Configure custom webhook-based tools

Create Agent

Core agent configuration

Dashboard testing

Test MCP tools in conversations

Troubleshooting

Debug tool invocation issues

Documentation Index

​Overview

​Set up MCP connections

​Configuration reference

​Required fields

​Optional fields

​Authentication types

​Transport types

​Tool filtering

​Precedence rules

​Test connections

​Common use cases

​MCP vs custom webhooks

​Best practices

​Security

​Performance

​Reliability

​Troubleshooting

​Next steps

Tools & functions

Create Agent

Dashboard testing

Troubleshooting

Overview

Set up MCP connections

Configuration reference

Required fields

Optional fields

Authentication types

Transport types

Tool filtering

Precedence rules

Test connections

Common use cases

MCP vs custom webhooks

Best practices

Security

Performance

Reliability

Troubleshooting

Next steps