MCP System Architecture

​

MCP Architecture Overview

​

What is MCP in Bifrost?

• 🔍 Dynamic Discovery - Tools are discovered at runtime, not hardcoded
• 🛡️ Client-Side Execution - Bifrost controls all tool execution for security
• 🌐 Multi-Protocol Support - STDIO, HTTP, and SSE connection types
• 🎯 Request-Level Filtering - Granular control over tool availability
• ⚡ Async Execution - Non-blocking tool invocation and response handling

​

MCP System Components

​

MCP Connection Architecture

​

Multi-Protocol Connection System

​

Connection Type Details

• Use Case: Command-line tools, local scripts, filesystem operations
• Performance: Lowest latency (~1-10ms) due to local execution
• Security: Highest security with full local control
• Limitations: Single-server deployment, resource sharing

• Use Case: Web APIs, microservices, cloud functions
• Performance: Network-dependent latency (~10-500ms)
• Security: Configurable with authentication and encryption
• Advantages: Scalable, multi-server deployment, service isolation

• Use Case: Real-time data feeds, live monitoring, event streams
• Performance: Variable latency depending on stream frequency
• Security: Similar to HTTP with streaming capabilities
• Benefits: Real-time updates, persistent connections, event-driven

📖 MCP Configuration: MCP Setup Guide →

​

🔍 Tool Discovery & Registration

​

Dynamic Tool Discovery Process

​

Tool Registry Management

1. Connection Establishment - MCP client connects to configured servers
2. Capability Exchange - Server announces available tools and schemas
3. Tool Validation - Bifrost validates tool definitions and security
4. Registry Update - Tools are registered in the internal tool registry
5. Availability Notification - Tools become available for AI model use

• Dynamic Updates - Tools can be added/removed during runtime
• Version Management - Support for tool versioning and compatibility
• Access Control - Request-level tool filtering and permissions
• Health Monitoring - Continuous tool availability checking

• Name & Description - Human-readable tool identification
• Parameters Schema - JSON schema for tool input validation
• Return Schema - Expected response format definition
• Capabilities - Tool feature flags and limitations
• Authentication - Required credentials and permissions

​

🎛️ Tool Filtering & Access Control

​

Multi-Level Filtering System

​

Filtering Configuration Levels

# Include only specific MCP clients
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "mcp-include-clients: filesystem,websearch" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

# Exclude dangerous tools
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "mcp-exclude-tools: delete_file,format_disk" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

• Client Selection - Choose which MCP servers to connect to
• Tool Blacklisting - Permanently disable dangerous or unwanted tools
• Permission Mapping - Map user roles to available tool sets
• Environment-Based - Different tool sets for development vs production

• Principle of Least Privilege - Only necessary tools are exposed
• Dynamic Access Control - Per-request tool availability
• Audit Trail - Track which tools are used by which requests
• Risk Mitigation - Prevent access to dangerous operations

​

⚙️ Tool Execution Engine

​

Async Tool Execution Architecture

​

Execution Flow Characteristics

• Parameter Validation - Ensure tool arguments match expected schema
• Permission Checking - Verify tool access permissions for the request
• Rate Limiting - Apply per-tool and per-user rate limits
• Security Scanning - Check for potentially dangerous operations

• Timeout Management - Bounded execution time to prevent hanging
• Error Handling - Graceful handling of tool failures and timeouts
• Result Streaming - Support for tools that return streaming responses
• Resource Monitoring - Track tool resource usage and performance

• Result Formatting - Convert tool outputs to consistent format
• Error Enrichment - Add context and suggestions for tool failures
• Multi-Result Aggregation - Combine multiple tool outputs coherently
• Context Integration - Merge tool results into conversation context

​

Multi-Turn Conversation Support

1. Initial Tool Discovery - Request available tools for a given context
2. Tool Execution - Execute one or more tools based on user request
3. Result Analysis - Analyze tool outputs and determine next steps
4. Follow-up Actions - Execute additional tools based on previous results
5. Response Synthesis - Combine tool results into coherent user response

User: "Find recent news about AI and save interesting articles"
AI: → Execute web_search("AI news recent")
AI: → Analyze search results
AI: → Execute save_article() for each interesting result
AI: → Respond with summary of saved articles

​

Complete User-Controlled Tool Execution Flow

• 🛡️ Security Layer - Your application controls all tool execution decisions
• 🤔 Approval Gate - Users can approve or deny each tool execution
• 📊 Transparency - Full visibility into what tools will be executed and why
• 🔄 Conversation Continuity - Tool results seamlessly integrate into conversation flow

• No Automatic Execution - Tools never execute without explicit approval
• Audit Trail - Complete logging of all tool execution decisions
• Contextual Security - Approval decisions can consider full conversation context
• Graceful Denials - Denied tools result in informative responses, not errors

// Example tool execution control in your application
func handleToolExecution(toolCall schemas.ToolCall, userContext UserContext) error {
    // YOUR SECURITY AND APPROVAL LOGIC HERE
    if !userContext.HasPermission(toolCall.Function.Name) {
        return createDenialResponse("Tool not permitted for user role")
    }

    if requiresApproval(toolCall) {
        approved := promptUserForApproval(toolCall)
        if !approved {
            return createDenialResponse("User denied tool execution")
        }
    }

    // Execute the tool via Bifrost
    result, err := client.ExecuteMCPTool(ctx, toolCall)
    if err != nil {
        return handleToolError(err)
    }

    return addToolResultToHistory(result)
}

​

🔧 MCP Integration Patterns

​

Common Integration Scenarios

• Tools: list_files, read_file, write_file, create_directory
• Use Cases: Code analysis, document processing, file management
• Security: Sandboxed file access, path validation, permission checks
• Performance: Local execution for fast file operations

• Tools: web_search, fetch_url, extract_content, summarize
• Use Cases: Research assistance, fact-checking, content gathering
• Integration: External search APIs, content parsing services
• Caching: Response caching for repeated queries

• Tools: query_database, insert_record, update_record, schema_info
• Use Cases: Data analysis, report generation, database administration
• Security: Read-only access by default, query validation, injection prevention
• Performance: Connection pooling, query optimization

• Tools: Custom business logic tools, third-party service integration
• Use Cases: CRM operations, payment processing, notification sending
• Authentication: API key management, OAuth token handling
• Error Handling: Retry logic, fallback mechanisms

​

MCP Server Development Patterns

• Language: Any language that can read/write JSON to stdin/stdout
• Deployment: Single executable, minimal dependencies
• Use Case: Local tools, development utilities, simple scripts

• Architecture: RESTful API with MCP protocol endpoints
• Scalability: Horizontal scaling, load balancing
• Use Case: Shared tools, enterprise integrations, cloud services

• Local + Remote: Combine STDIO tools for local operations with HTTP for remote services
• Failover: Use local fallbacks when remote services are unavailable
• Optimization: Route tool calls to most appropriate execution environment

​

🛡️ Security & Safety Considerations

​

MCP Security Architecture

• Authentication - API keys, certificates, or token-based auth for HTTP/SSE
• Encryption - TLS for HTTP connections, secure pipes for STDIO
• Network Isolation - Firewall rules and network segmentation

• Sandboxing - Isolated execution environments for tools
• Resource Limits - CPU, memory, and time constraints
• Permission Model - Principle of least privilege for tool access

• Input Validation - Strict parameter validation before tool execution
• Output Sanitization - Remove sensitive data from tool responses
• Audit Logging - Complete audit trail of tool usage

• Regular Updates - Keep MCP servers and tools updated
• Monitoring - Continuous security monitoring and alerting
• Incident Response - Procedures for security incidents involving tools