API
MCP Integration

MCP Integration

NudgeLang integrates with the Model Context Protocol (MCP) to provide access to external services that offer prompts, resources, and tools following the MCP specification. This document covers the integration features, configuration, and best practices.

Basic Structure 

mcp:
  enabled: boolean        # Required: Enable MCP integration
  version: string         # Required: MCP version
  config:                 # Required: MCP configuration
    host: string          # Required: MCP host
    port: number          # Required: MCP port
    auth:                 # Required: Authentication
      type: string        # Required: Auth type
      credentials: object # Required: Auth credentials
  servers:               # Required: MCP server configurations
    - id: string         # Required: Server identifier
      endpoint: string   # Required: Server endpoint
      capabilities:      # Required: Server capabilities
        resources: boolean  # Can provide resources
        prompts: boolean   # Can provide prompts
        tools: boolean     # Can provide tools

Configuration

Basic Configuration 

mcp:
  enabled: true
  version: "1.0.0"
  config:
    host: "mcp.example.com"
    port: 8080
    auth:
      type: "api_key"
      credentials:
        api_key: "${env.MCP_API_KEY}"

Advanced Configuration 

mcp:
  enabled: true
  version: "1.0.0"
  config:
    host: "mcp.example.com"
    port: 8080
    auth:
      type: "oauth2"
      credentials:
        client_id: "${env.MCP_CLIENT_ID}"
        client_secret: "${env.MCP_CLIENT_SECRET}"
    ssl:
      enabled: true
      verify: true
    timeout: 5000
    retry_attempts: 3

Server Configuration

Basic Server 

mcp:
  servers:
    - id: "knowledge_base"
      endpoint: "https://api.example.com/kb"
      description: "Product knowledge base with documentation and FAQs"
      capabilities:
        resources: true
        prompts: true
        tools: true
      auth:
        type: "bearer"
        token_env: "KB_API_TOKEN"

Advanced Server 

mcp:
  servers:
    - id: "custom_server"
      endpoint: "https://api.example.com/mcp"
      description: "Custom MCP server with specialized capabilities"
      capabilities:
        resources: true
        prompts: true
        tools: true
      auth:
        type: "custom"
        headers:
          X-API-Key: "${env.CUSTOM_API_KEY}"
      options:
        timeout: 5000
        retry_attempts: 3
        cache_enabled: true

Server Usage

Basic Usage 

states:
  - id: use_server
    type: mcp
    server: "knowledge_base"
    action: "get_resource"
    input:
      resource_id: "${input.resource_id}"
    next: next_state

Advanced Usage 

states:
  - id: use_server
    type: mcp
    server: "custom_server"
    action: "get_prompt"
    input:
      prompt_id: "${input.prompt_id}"
      parameters:
        param1: "value1"
        param2: "value2"
    next: next_state

Server Management

Resource Management 

mcp:
  servers:
    - id: "resource_server"
      endpoint: "https://api.example.com/resources"
      capabilities:
        resources: true
      auth:
        type: "bearer"
        token_env: "RESOURCE_API_TOKEN"
      options:
        resource_cache:
          enabled: true
          ttl: 3600

Tool Management 

mcp:
  servers:
    - id: "tool_server"
      endpoint: "https://api.example.com/tools"
      capabilities:
        tools: true
      auth:
        type: "bearer"
        token_env: "TOOL_API_TOKEN"
      options:
        tool_validation:
          enabled: true
          timeout: 5000

Monitoring

Basic Monitoring 

mcp:
  monitoring:
    enabled: true
    metrics:
      - server_availability
      - response_time
      - error_rate
    alerts:
      - name: "server_down"
        condition: "availability < 0.99"
        action: "notify"

Advanced Monitoring 

mcp:
  monitoring:
    enabled: true
    metrics:
      - server_availability
      - response_time
      - error_rate
      - resource_usage
      - tool_usage
    alerts:
      - name: "server_down"
        condition: "availability < 0.99"
        action: "notify"
      - name: "high_error_rate"
        condition: "error_rate > 0.01"
        action: "alert"
    dashboards:
      - name: "server_performance"
        metrics:
          - server_availability
          - response_time
          - error_rate

Best Practices

  1. Configuration

    • Use environment variables
    • Enable SSL
    • Set timeouts
    • Configure retries

  2. Server Management

    • Use versioning
    • Enable monitoring
    • Configure validation
    • Set rate limits

  3. Security

    • Use secure auth
    • Enable SSL
    • Validate inputs
    • Handle secrets

  4. Monitoring

    • Track metrics
    • Set alerts
    • Use dashboards
    • Monitor usage

Common Patterns

  1. Resource Server
mcp:
  servers:
    - id: "resource_server"
      endpoint: "https://api.example.com/resources"
      capabilities:
        resources: true
      auth:
        type: "bearer"
        token_env: "RESOURCE_API_TOKEN"
      options:
        resource_cache:
          enabled: true
          ttl: 3600
  1. Tool Server
mcp:
  servers:
    - id: "tool_server"
      endpoint: "https://api.example.com/tools"
      capabilities:
        tools: true
      auth:
        type: "bearer"
        token_env: "TOOL_API_TOKEN"
      options:
        tool_validation:
          enabled: true
          timeout: 5000
  1. Server Monitoring
mcp:
  monitoring:
    enabled: true
    metrics:
      - server_availability
      - response_time
      - error_rate
    alerts:
      - name: "server_down"
        condition: "availability < 0.99"
        action: "notify"
      - name: "high_error_rate"
        condition: "error_rate > 0.01"
        action: "alert"

Next Steps

Last updated on
Tool Definitions