Skip to main content
Version: 0.7.0

Connecting to an external MCP server

Introduced 0.7.0

The Lucenia MCP client allows Lucenia agents to connect to external tool providers through the MCP protocol, significantly expanding their capabilities beyond native Lucenia functions. Rather than being limited to built-in tools, agents can use specialized external services like weather forecasts, translation APIs, document processing tools, and more.

Prerequisites​

Before connecting to an external MCP server, ensure that:

  1. The external MCP server is running and accessible
  2. You have the necessary authentication credentials
  3. The MCP server supports the required tools for your use case
  4. Network connectivity allows communication between Lucenia and the external server

Configuration​

To connect Lucenia agents to an external MCP server, you need to configure the connection parameters in your agent registration.

Basic connection configuration​

POST /_plugins/_ml/agents/_register
{
  "name": "external_mcp_agent",
  "type": "conversational",
  "description": "Agent using external MCP tools",
  "parameters": {
    "mcp_server": {
      "endpoint": "https://external-mcp-server.example.com/mcp",
      "transport": "sse",
      "authentication": {
        "type": "bearer_token",
        "token": "your-auth-token"
      }
    }
  }
}

Advanced configuration options​

POST /_plugins/_ml/agents/_register
{
  "name": "advanced_mcp_agent",
  "type": "conversational",
  "description": "Agent with advanced MCP configuration",
  "parameters": {
    "mcp_server": {
      "endpoint": "https://external-mcp-server.example.com/mcp",
      "transport": "sse",
      "authentication": {
        "type": "api_key",
        "api_key": "your-api-key",
        "header_name": "X-API-Key"
      },
      "connection_settings": {
        "timeout_ms": 30000,
        "retry_attempts": 3,
        "keep_alive": true
      },
      "allowed_tools": [
        "weather_forecast",
        "document_translator",
        "image_analyzer"
      ]
    }
  }
}

Authentication methods​

The MCP client supports several authentication methods:

Bearer token authentication​

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

API key authentication​

{
  "authentication": {
    "type": "api_key",
    "api_key": "your-api-key",
    "header_name": "X-API-Key"
  }
}

Basic authentication​

{
  "authentication": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Custom headers​

{
  "authentication": {
    "type": "custom_headers",
    "headers": {
      "Authorization": "Custom auth-value",
      "X-Client-ID": "lucenia-client"
    }
  }
}

Connection management​

Connection lifecycle​

  1. Discovery: The agent discovers available tools from the external MCP server
  2. Authentication: Establishes authenticated connection using provided credentials
  3. Tool registration: Available tools are registered for use by the agent
  4. Execution: Tools are invoked as needed during agent conversations
  5. Cleanup: Connections are properly closed when the agent is decommissioned

Error handling​

The MCP client implements robust error handling:

  • Connection failures: Automatic retry with exponential backoff
  • Authentication errors: Clear error messages for troubleshooting
  • Tool execution errors: Graceful degradation with fallback options
  • Network timeouts: Configurable timeout settings

Example: Weather service integration​

Here's a complete example of connecting to a weather service MCP server:

{
  "name": "weather_assistant",
  "type": "conversational",
  "description": "Assistant with access to weather data",
  "parameters": {
    "mcp_server": {
      "endpoint": "https://weather-mcp.example.com/mcp/sse",
      "transport": "sse",
      "authentication": {
        "type": "api_key",
        "api_key": "weather-api-key-123",
        "header_name": "X-Weather-API-Key"
      },
      "allowed_tools": [
        "get_current_weather",
        "get_weather_forecast",
        "get_weather_alerts"
      ]
    },
    "model_id": "your-llm-model-id"
  }
}

Once registered, the agent can use weather tools in conversations:

User: What's the weather like in Seattle today?
Agent: I'll check the current weather in Seattle for you.
[Agent uses get_current_weather tool via MCP]
Agent: The current weather in Seattle is partly cloudy with a temperature of 68°F...

Monitoring and troubleshooting​

Connection status​

Check the connection status of your MCP-enabled agents:

GET /_plugins/_ml/agents/{agent_id}/status

Logs​

Monitor MCP connection logs in the Lucenia logs:

tail -f logs/lucenia.log | grep "MCP"

Common issues​

  1. Connection refused: Verify the external MCP server is running and accessible
  2. Authentication failed: Check credentials and authentication method
  3. Tool not found: Ensure the requested tool is available on the external server
  4. Timeout errors: Adjust timeout settings in the connection configuration

Security considerations​

  • Credential management: Store API keys and tokens securely using Lucenia's keystore
  • Network security: Use HTTPS for all external MCP connections
  • Tool restrictions: Limit available tools using the allowed_tools configuration
  • Access control: Implement proper role-based access control for MCP-enabled agents

Next steps​