Skip to content

EXTERNAL_MCP_INTEGRATION.md

Latest commit

 

History

History
305 lines (249 loc) · 7.08 KB

EXTERNAL_MCP_INTEGRATION.md

File metadata and controls

305 lines (249 loc) · 7.08 KB

External MCP Server Integration Guide

Overview

The BotForge RAG API now supports external MCP (Model Context Protocol) server integration, allowing businesses to register their own MCP servers and make their tools available through the bot interface.

Features

  • External MCP Server Registration: Businesses can register their MCP servers with specific bots
  • Tool Discovery: Automatic discovery and registration of available tools from external MCP servers
  • Unified Query Interface: Both information retrieval and tool execution through a single query interface
  • Health Monitoring: Monitor the health and availability of external MCP servers
  • Usage Tracking: Track tool usage and execution history
  • Security: API key-based authentication for external MCP servers

API Endpoints

1. Register MCP Server

Register a new external MCP server for a bot.

POST /api/mcp/register

Request Body:

{
  "bot_id": "bot-uuid",
  "name": "My Business MCP Server",
  "endpoint_url": "https://api.mybusiness.com/mcp",
  "description": "Customer management and order processing tools",
  "api_key": "your-api-key",
  "timeout_seconds": 30,
  "retry_attempts": 3,
  "config": {
    "custom_setting": "value"
  }
}

Response:

{
  "success": true,
  "mcp_server_id": "server-uuid",
  "tools_registered": 5,
  "server_info": {
    "name": "My Business MCP Server",
    "tools": [...]
  },
  "message": "MCP server registered successfully with 5 tools"
}

2. Get Bot MCP Servers

List all MCP servers registered for a bot.

GET /api/mcp/servers/{bot_id}

Response:

{
  "bot_id": "bot-uuid",
  "servers": [
    {
      "id": "server-uuid",
      "name": "My Business MCP Server",
      "description": "Customer management tools",
      "endpoint_url": "https://api.mybusiness.com/mcp",
      "is_active": true,
      "tools_count": 5,
      "created_at": "2025-07-03T15:00:00Z"
    }
  ],
  "total_count": 1
}

3. Execute External MCP Tool

Execute a tool from an external MCP server.

POST /api/mcp/execute

Request Body:

{
  "bot_id": "bot-uuid",
  "tool_name": "get_customer_info",
  "parameters": {
    "customer_id": "12345"
  },
  "user_id": "user-uuid"
}

Response:

{
  "success": true,
  "tool_name": "get_customer_info",
  "result": {
    "customer": {
      "id": "12345",
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  "execution_time_ms": 250,
  "error": null
}

4. Check MCP Server Health

Check the health status of all MCP servers for a bot.

GET /api/mcp/servers/{bot_id}/health

Response:

{
  "bot_id": "bot-uuid",
  "overall_health": true,
  "servers": [
    {
      "server_id": "server-uuid",
      "server_name": "My Business MCP Server",
      "status": "healthy",
      "tools_available": 5
    }
  ],
  "timestamp": "2025-07-03T15:30:00Z"
}

5. Get MCP Server Tools

Get all tools for a specific MCP server.

GET /api/mcp/tools/{mcp_server_id}

Response:

{
  "mcp_server_id": "server-uuid",
  "tools": [
    {
      "id": "tool-uuid",
      "name": "get_customer_info",
      "description": "Retrieve customer information",
      "schema": {
        "type": "object",
        "properties": {
          "customer_id": {"type": "string"}
        }
      },
      "is_active": true,
      "usage_count": 42,
      "last_used": "2025-07-03T15:00:00Z"
    }
  ],
  "total_count": 1
}

6. Update MCP Server

Update an existing MCP server configuration.

PUT /api/mcp/servers/{mcp_server_id}

Request Body:

{
  "name": "Updated Server Name",
  "description": "Updated description",
  "endpoint_url": "https://new-api.mybusiness.com/mcp",
  "is_active": false
}

7. Delete MCP Server

Delete an MCP server and all its tools.

DELETE /api/mcp/servers/{mcp_server_id}

Query Interface with Intent Detection

The bot now supports intent detection to automatically route queries to either information retrieval (RAG) or tool execution (MCP).

Query with Intent Detection

POST /vector/query-with-intent

Request Body:

{
  "user_id": "user-uuid",
  "bot_id": "bot-uuid",
  "client_id": "client-uuid",
  "query": "Get customer information for John Doe",
  "model": "gpt-3.5-turbo",
  "top_k": 5,
  "max_tokens": 1000,
  "temperature": 0.7
}

Response:

{
  "user_id": "user-uuid",
  "bot_id": "bot-uuid",
  "query": "Get customer information for John Doe",
  "model": "gpt-3.5-turbo",
  "response": "I found the customer information for John Doe...",
  "intent": "execution",
  "processing_type": "execution",
  "execution_analysis": {
    "action_type": "get_customer_info",
    "target": "John Doe"
  },
  "mcp_result": {
    "success": true,
    "available_tools": [...],
    "external_tools": [...]
  },
  "execution_time": 1.25
}

MCP Server Requirements

External MCP servers must implement the following endpoints:

1. Server Information

GET /info

Response should include server name, description, and available tools.

2. Tool Execution

POST /execute

Request body should include tool name and parameters.

Example Business Integration

Here's how a business might integrate their customer management system:

  1. Register MCP Server: Register their customer API as an MCP server
  2. Tool Registration: Tools like get_customer_info, create_order, update_customer are automatically registered
  3. Query Integration: Users can ask "What's John Doe's email?" and the bot will automatically execute the appropriate tool
  4. Response Generation: The bot uses the tool result to generate a natural language response

Security Considerations

  • API Keys: Store and use API keys securely for external MCP server authentication
  • Rate Limiting: Implement rate limiting to prevent abuse
  • Input Validation: Validate all parameters before sending to external servers
  • Error Handling: Gracefully handle external server failures
  • Logging: Log all external tool executions for audit purposes

Monitoring and Analytics

  • Usage Tracking: Track tool usage frequency and execution times
  • Health Monitoring: Monitor external server availability and response times
  • Error Tracking: Track and alert on tool execution failures
  • Performance Metrics: Monitor query response times and success rates

Future Enhancements

  • Webhook Support: Support for external servers to push updates
  • Caching: Cache external tool results to improve performance
  • Advanced Authentication: Support for OAuth and other authentication methods
  • Tool Composition: Allow chaining of multiple tools for complex workflows
  • Custom UI: Generate custom UI components for complex tools

Getting Started

  1. Deploy your MCP server with the required endpoints
  2. Register your server using the /api/mcp/register endpoint
  3. Test tool execution using the /api/mcp/execute endpoint
  4. Enable users to interact with your tools through natural language queries

For more information and examples, see the API documentation at /docs when the server is running.