MCP Connections

Model Context Protocol (MCP) is an open-source standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. By configuring MCP connections, you can expand your agent’s capabilities beyond conversation to include actions like database queries, file operations, API integrations, and more.

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

What is Model Context Protocol?

The Model Context Protocol standardizes how AI agents interact with external tools and data sources. Instead of building custom integrations for each system, MCP provides a unified interface that works across different AI models and data sources.

Key Benefits

Universal Standard

One protocol for all tool integrations
Works with supported LLM providers (OpenAI, Groq, Grok, DeepSeek, custom-compatible)
Growing ecosystem of pre-built MCP servers

Secure Connections

Authentication support (API keys, Bearer tokens)
Custom headers for additional security
Tool-level access control (whitelist/blacklist)

Rich Capabilities

Access to file systems, databases, APIs
Execute complex workflows
Real-time data retrieval
Multi-step tool orchestration

Standardized Discovery

Automatic tool discovery from MCP servers
Self-describing tool schemas
Built-in validation and error handling

How MCP Works

Connection Setup: Configure your agent to connect to an MCP server
Tool Discovery: Platform automatically discovers available tools from the server
Runtime Invocation: During conversations, agent can call discovered tools
Secure Execution: MCP server executes operations with proper authentication
Result Integration: Tool results are incorporated into agent responses

Setting Up MCP Connections

Via Dashboard

Navigate to the MCP Connections tab in the agent creation/edit form.

Add New Connection

Click “Add MCP Connection” button to create a new connection configuration.

Configure Connection Details

Fill in the required fields:

Name: Descriptive identifier (e.g., “GitHub API”, “Company Database”)
Server URL: HTTP/HTTPS endpoint of your MCP server
Description: Optional notes about this connection’s purpose

Set Up Authentication

Choose authentication method:

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

Configure Transport

Select transport method:

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

Test Connection

Click “Test Connection” to verify:

Server is reachable
Authentication is valid
Tools are discoverable

You’ll see a list of available tools if successful.

Enable Connection

Toggle the connection status to enable or disable it. Only enabled connections are used by agents during runtime.

Via API

Use the agent creation or update endpoint to configure MCP connections:

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: {
      version: "v1",
      primaryLanguage: "en-US",
      llmConfig: {
        version: "v1",
        vendor: "openai",
        model: "gpt-4.1",
        prompt: "You are a customer support agent with access to CRM data..."
      },
      ttsConfig: {
        version: "v1",
        vendor: "ElevenLabs",
        voiceId: "zmcVlqmyk3Jpn5AVYcAL",
        model: "eleven_flash_v2_5",
        speed: 1.0
      },
      mcpConnections: [
        {
          name: "Customer CRM",
          serverUrl: "https://mcp.example.com/crm",
          description: "Access to customer records and order history",
          authentication: {
            type: "apiKey",
            headerName: "X-API-Key",
            apiKey: "YOUR_CRM_API_KEY"
          },
          transport: "StreamableHTTP",
          isEnabled: true,
          whiteListTools: [
            "get_customer_info",
            "get_order_history",
            "update_customer_notes"
          ]
        }
      ]
    }
  })
});

Connection 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	Description
`description`	string	Human-readable description of the connection
`authentication`	object	Authentication configuration (see below)
`customHeaders`	object	Additional HTTP headers to include in requests
`isEnabled`	boolean	Whether this connection is active (default: true)
`transport`	enum	Transport method: “SSE” or “StreamableHTTP”
`whiteListTools`	string[]	API-only: Array of tool names to enable (if set, only these are available)
`blackListTools`	string[]	API-only: Array of tool names to disable (all others are available)

Authentication Types

No Authentication

For public or internal MCP servers that don’t require authentication:

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

API Key Authentication

For servers that use API keys in custom headers:

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

The headerName field is optional and defaults to X-API-Key if not specified. You can override it when your MCP server expects a different header name. Common header names:

X-API-Key
X-Auth-Token
API-Key

Bearer Token Authentication

For OAuth 2.0 or similar token-based authentication:

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

Custom Headers

Add additional HTTP headers for advanced authentication or routing:

{
  "customHeaders": {
    "X-Organization-ID": "org-12345",
    "X-Environment": "production",
    "User-Agent": "BlackBox-Agent/1.0"
  }
}

Testing MCP Connections

Connection Verification API

Use the MCP verify endpoint to test connections before saving:

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 successful:', verification.success);
console.log('Available tools:', verification.availableTools);
console.log('Response time:', verification.responseTimeMs, 'ms');

Verification Response

Successful verification returns:

{
  "success": true,
  "message": "Connection successful",
  "availableTools": [
    {
      "name": "get_customer_info",
      "description": "Retrieve customer information by ID or email",
      "schema": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "Customer ID or email address"
          }
        },
        "required": ["customerId"]
      },
      "isEnabled": true
    },
    {
      "name": "update_customer_notes",
      "description": "Add notes to customer record",
      "schema": {
        "type": "object",
        "properties": {
          "customerId": { "type": "string" },
          "note": { "type": "string" }
        },
        "required": ["customerId", "note"]
      },
      "isEnabled": true
    }
  ],
  "testedAt": "2025-10-20T14:30:00Z",
  "responseTimeMs": 145.2
}

Via Dashboard

The dashboard provides a visual interface for testing:

Test Button: Click “Test Connection” on any MCP connection card
Status Indicator: Green checkmark for success, red X for failure
Available Tools: Expandable list showing discovered tools and their schemas
Response Time: Shows server response latency
Error Details: If connection fails, shows specific error message

Tool Access Control (API Only)

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

Whitelisting Tools

Only allow specific tools from an MCP server via API:

{
  "name": "Read-Only Database",
  "serverUrl": "https://mcp.example.com/db",
  "whiteListTools": [
    "query_customers",
    "query_orders",
    "query_products"
  ]
}

With this configuration:

✅ query_customers, query_orders, query_products are available
❌ All other tools (e.g., delete_record, update_customer) are blocked

Blacklisting Tools

Block specific dangerous or unnecessary tools via API:

{
  "name": "CRM API",
  "serverUrl": "https://mcp.example.com/crm",
  "blackListTools": [
    "delete_customer",
    "delete_all_records",
    "export_database"
  ]
}

With this configuration:

✅ All tools except those in blacklist are available
❌ delete_customer, delete_all_records, export_database are blocked

Whitelist vs Blacklist: You cannot use both whiteListTools and blackListTools on the same connection. Choose one approach based on your security needs.

Transport Types

Server-Sent Events (SSE)

Best for:

Streaming data sources
Real-time updates
Long-running operations
Event-driven tools

{
  "transport": "SSE",
  "serverUrl": "https://mcp.example.com/stream"
}

Characteristics:

Maintains open connection for server-to-client streaming
Low latency for real-time data
Automatic reconnection on connection loss

StreamableHTTP

Best for:

Request/response APIs
Traditional REST endpoints
Simple tool invocations
Batch operations

{
  "transport": "StreamableHTTP",
  "serverUrl": "https://mcp.example.com/api"
}

Characteristics:

Standard HTTP request/response cycle
No persistent connection overhead
Works with any HTTP-compatible MCP server

Available MCP Tools

Once connected, your agent can automatically discover and use tools provided by the MCP server. Tools appear in your agent’s capability list and can be invoked during conversations.

Tool Structure

Each MCP tool includes:

{
  name: string;          // Tool identifier (e.g., "get_weather")
  description: string;   // Human-readable description
  schema: {             // JSON Schema for parameters
    type: "object",
    properties: { ... },
    required: [ ... ]
  };
  isEnabled: boolean;   // Whether tool is currently active
}

Example Tools

Database Query Tool:

{
  "name": "query_database",
  "description": "Execute a SQL query against the customer database",
  "schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "SQL SELECT query to execute"
      },
      "limit": {
        "type": "number",
        "description": "Maximum rows to return",
        "default": 100
      }
    },
    "required": ["query"]
  },
  "isEnabled": true
}

File Retrieval Tool:

{
  "name": "read_file",
  "description": "Read contents of a file from the document repository",
  "schema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path relative to repository root"
      },
      "encoding": {
        "type": "string",
        "enum": ["utf-8", "base64"],
        "default": "utf-8"
      }
    },
    "required": ["path"]
  },
  "isEnabled": true
}

Runtime Behavior

How Agents Use MCP Tools

During conversations, your agent’s LLM decides when to invoke MCP tools based on:

User Intent: Questions or requests that require external data
Tool Descriptions: Matching tool capabilities to user needs
Context: Previous conversation context and available information

Example Conversation:

User: "What's the status of order #12345?"

Agent (internal):
  - User is asking about order status
  - I have access to "get_order_status" MCP tool
  - Tool requires orderId parameter
  - Invoking: get_order_status(orderId: "12345")

MCP Tool Response:
  {
    "orderId": "12345",
    "status": "shipped",
    "trackingNumber": "1Z999AA10123456784",
    "estimatedDelivery": "2025-10-25"
  }

Agent (to user):
  "Order #12345 has been shipped! Your tracking number is 1Z999AA10123456784,
   and the estimated delivery date is October 25th."

Tool Invocation Flow

LLM Decision: Agent’s LLM determines a tool is needed
Parameter Extraction: LLM extracts required parameters from context
Validation: Platform validates parameters against tool schema
MCP Call: Platform sends request to MCP server with authentication
Execution: MCP server executes operation on external system
Response: Result is returned to the agent
Integration: Agent incorporates result into its response

Error Handling

If a tool call fails, the agent receives an error message and can:

Retry with corrected parameters
Explain the issue to the user
Fall back to alternative approaches

Common Use Cases

CRM Integration

Connect to your CRM system for customer support:

{
  "name": "Salesforce CRM",
  "serverUrl": "https://mcp.yourcompany.com/salesforce",
  "description": "Access to customer records, cases, and opportunities",
  "authentication": {
    "type": "bearer",
    "token": "YOUR_SALESFORCE_TOKEN"
  },
  "whiteListTools": [
    "get_customer_by_email",
    "get_open_cases",
    "create_case",
    "update_case_status"
  ]
}

Agent Capabilities:

Look up customer information during calls
Check open support tickets
Create new support cases
Update case statuses

Database Access

Connect to your database for data-driven conversations:

{
  "name": "Analytics Database",
  "serverUrl": "https://mcp.yourcompany.com/postgres",
  "description": "Read-only access to analytics database",
  "authentication": {
    "type": "apiKey",
    "headerName": "X-DB-Key",
    "apiKey": "YOUR_DB_API_KEY"
  },
  "whiteListTools": [
    "query_sales_data",
    "query_user_metrics",
    "query_product_inventory"
  ]
}

Agent Capabilities:

Answer questions with live data
Provide real-time metrics
Check product availability
Generate data-driven insights

Document Repository

Connect to document storage for knowledge retrieval:

{
  "name": "Knowledge Base",
  "serverUrl": "https://mcp.yourcompany.com/docs",
  "description": "Company documentation and knowledge articles",
  "transport": "SSE",
  "authentication": {
    "type": "none"
  }
}

Agent Capabilities:

Search company documentation
Retrieve specific articles
Reference technical specifications
Provide accurate product information

API Integration

Connect to third-party APIs:

{
  "name": "Weather API",
  "serverUrl": "https://mcp.yourcompany.com/weather",
  "description": "Real-time weather data and forecasts",
  "authentication": {
    "type": "apiKey",
    "headerName": "X-API-Key",
    "apiKey": "YOUR_WEATHER_API_KEY"
  }
}

Agent Capabilities:

Provide current weather conditions
Offer forecasts for planning
Weather-based recommendations
Location-specific information

Best Practices

Security

Principle of Least Privilege

Use whitelisting to expose only necessary tools
Avoid granting access to destructive operations (delete, drop, etc.)
Regularly audit enabled tools

Authentication

Always use authentication for production MCP servers
Rotate API keys and tokens regularly
Use environment-specific credentials

Network Security

Use HTTPS for all MCP server URLs
Consider IP whitelisting on MCP server side
Monitor for unusual tool invocation patterns

Performance

Connection Pooling

MCP connections are reused across calls
No need to optimize for connection overhead
Focus on tool response times

Response Times

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

Rate Limiting

Implement rate limits on your MCP server
Handle rate limit errors gracefully
Provide clear error messages to the agent

Reliability

Error Handling

Return descriptive error messages
Use appropriate HTTP status codes
Implement retries for transient failures

Monitoring

Log all MCP tool invocations
Track success/failure rates
Monitor response times

Fallbacks

Design tools to degrade gracefully
Provide partial results when possible
Consider tool redundancy for critical operations

Troubleshooting

Connection Failures

Symptom: “Connection failed” or “Server unreachable” errors Solutions:

✅ Verify serverUrl is correct and accessible
✅ Check authentication credentials are valid
✅ Ensure MCP server is running and healthy
✅ Verify network connectivity (firewalls, proxies)
✅ Check server logs for error details

Authentication Errors

Symptom: 401 Unauthorized or 403 Forbidden responses Solutions:

✅ Verify authentication type matches server expectations
✅ Check API key or token is correct and not expired
✅ Ensure headerName matches what server expects
✅ Verify custom headers are formatted correctly
✅ Test authentication separately with curl or Postman

Tool Discovery Issues

Symptom: No tools appear after connection test, or fewer tools than expected Solutions:

✅ Verify MCP server implements tool listing endpoint correctly
✅ Check whiteListTools isn’t too restrictive
✅ Ensure tools aren’t disabled on server side
✅ Verify MCP server response format matches protocol spec
✅ Check for server-side errors in logs

Tool Invocation Failures

Symptom: Tools fail when called during conversations Solutions:

✅ Verify tool schemas match actual parameter requirements
✅ Check for parameter validation errors
✅ Ensure external system (database, API) is accessible
✅ Monitor MCP server logs for execution errors
✅ Test tools independently outside of conversation flow

Performance Issues

Symptom: Slow responses or timeouts Solutions:

✅ Optimize database queries or API calls on MCP server
✅ Implement caching for frequently accessed data
✅ Use connection pooling for database connections
✅ Consider switching to SSE transport for streaming
✅ Monitor server resource utilization (CPU, memory, network)

Comparison: MCP Tools vs Custom Webhooks

Feature	MCP Tools	Custom Webhooks
Setup Complexity	Requires MCP server	Direct webhook endpoint
Tool Discovery	Automatic	Manual configuration
Schema Validation	Built-in	Custom implementation
Authentication	Standardized	Custom per endpoint
Error Handling	Protocol-level	Custom per webhook
Retry Logic	Platform-managed	Custom implementation
Best For	Multiple related tools	Single-purpose actions

When to use MCP:

✅ Multiple related tools from same system
✅ Dynamic tool discovery needed
✅ Standardized authentication
✅ Complex tool ecosystems

When to use Custom Webhooks:

✅ Single-purpose tool/action
✅ Legacy systems without MCP support
✅ Simple integrations
✅ Custom execution logic required

Tools & Functions - Learn about custom webhook-based tools
Agent Basics - Core agent configuration
Testing Tools - Test MCP tools in the dashboard
Debugging Agents - Debug tool invocation issues

API Reference

POST /api/v1/mcp/verify - Verify MCP connection
POST /api/v1/agents - Create agent with MCP connections
PUT /api/v1/agents/ - Update agent MCP connections

The Model Context Protocol is an open standard developed by Anthropic and adopted by major AI platforms. It provides a secure, standardized way to connect AI agents to external data and tools.

Introduction

Build

WebSockets

​MCP Connections

​What is Model Context Protocol?

​Key Benefits

​How MCP Works

​Setting Up MCP Connections

​Via Dashboard

​Via API

​Connection Configuration Reference

​Required Fields

​Optional Fields

​Authentication Types

​No Authentication

​API Key Authentication

​Bearer Token Authentication

​Custom Headers

​Testing MCP Connections

​Connection Verification API

​Verification Response

​Via Dashboard

​Tool Access Control (API Only)

​Whitelisting Tools

​Blacklisting Tools

​Transport Types

​Server-Sent Events (SSE)

​StreamableHTTP

​Available MCP Tools

​Tool Structure

​Example Tools

​Runtime Behavior

​How Agents Use MCP Tools

​Tool Invocation Flow

​Error Handling

​Common Use Cases

​CRM Integration

​Database Access

​Document Repository

​API Integration

​Best Practices

​Security

​Performance

​Reliability

​Troubleshooting

​Connection Failures

​Authentication Errors

​Tool Discovery Issues

​Tool Invocation Failures

​Performance Issues

​Comparison: MCP Tools vs Custom Webhooks

​Related Documentation

​API Reference

MCP Connections

What is Model Context Protocol?

Key Benefits

How MCP Works

Setting Up MCP Connections

Via Dashboard

Via API

Connection Configuration Reference

Required Fields

Optional Fields

Authentication Types

No Authentication

API Key Authentication

Bearer Token Authentication

Custom Headers

Testing MCP Connections

Connection Verification API

Verification Response

Via Dashboard

Tool Access Control (API Only)

Whitelisting Tools

Blacklisting Tools

Transport Types

Server-Sent Events (SSE)

StreamableHTTP

Available MCP Tools

Tool Structure

Example Tools

Runtime Behavior

How Agents Use MCP Tools

Tool Invocation Flow

Error Handling

Common Use Cases

CRM Integration

Database Access

Document Repository

API Integration

Best Practices

Security

Performance

Reliability

Troubleshooting

Connection Failures

Authentication Errors

Tool Discovery Issues

Tool Invocation Failures

Performance Issues

Comparison: MCP Tools vs Custom Webhooks

Related Documentation

API Reference