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.

Lucenia supports MCP servers that use the Streamable HTTP protocol. Standard Input/Output (stdio) protocol is not supported.

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 Streamable HTTP transport protocol
4. Network connectivity allows communication between Lucenia and the external server

Creating an MCP connector

To connect to an external MCP server, create an MCP connector using the Connectors API.

Request

POST /_plugins/_ml/connectors/_create
{
  "name": "My MCP Connector",
  "description": "Connects to an external MCP server using Streamable HTTP",
  "version": 1,
  "protocol": "mcp_streamable_http",
  "url": "https://my-mcp-server.example.com",
  "credential": {
    "mcp_server_key": "YOUR_MCP_SERVER_API_KEY"
  },
  "parameters": {
    "endpoint": "/mcp"
  },
  "headers": {
    "Authorization": "Bearer ${credential.mcp_server_key}"
  }
}

Request fields

Field	Type	Description	Required
name	String	Name for the connector	Yes
description	String	Description of the connector	No
version	Integer	Connector version	Yes
protocol	String	Must be mcp_streamable_http	Yes
url	String	Base URL of the external MCP server	Yes
credential	Object	Authentication credentials	No
parameters.endpoint	String	MCP endpoint path (default: /mcp)	No
headers	Object	Custom headers to include in requests	No

Example response

{
  "connector_id": "abc123def456"
}

Authentication methods

The MCP connector supports several authentication methods:

Bearer token authentication

{
  "protocol": "mcp_streamable_http",
  "url": "https://my-mcp-server.example.com",
  "credential": {
    "mcp_server_key": "your-bearer-token"
  },
  "headers": {
    "Authorization": "Bearer ${credential.mcp_server_key}"
  }
}

API key authentication

{
  "protocol": "mcp_streamable_http",
  "url": "https://my-mcp-server.example.com",
  "credential": {
    "api_key": "your-api-key"
  },
  "headers": {
    "X-API-Key": "${credential.api_key}"
  }
}

Basic authentication

{
  "protocol": "mcp_streamable_http",
  "url": "https://my-mcp-server.example.com",
  "credential": {
    "username": "your-username",
    "password": "your-password"
  },
  "headers": {
    "Authorization": "Basic ${credential.username}:${credential.password}"
  }
}

Using an MCP connector with agents

After creating an MCP connector, you can use it with an agent to access external MCP tools.

Register an agent with MCP connector

POST /_plugins/_ml/agents/_register
{
  "name": "external_mcp_agent",
  "type": "conversational",
  "description": "Agent using external MCP tools",
  "llm": {
    "model_id": "your-llm-model-id"
  },
  "tools": [
    {
      "type": "MCPTool",
      "parameters": {
        "connector_id": "abc123def456"
      }
    }
  ]
}

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 connector 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:

Step 1: Create the connector

POST /_plugins/_ml/connectors/_create
{
  "name": "Weather MCP Connector",
  "description": "Connects to weather service MCP server",
  "version": 1,
  "protocol": "mcp_streamable_http",
  "url": "https://weather-mcp.example.com",
  "credential": {
    "api_key": "weather-api-key-123"
  },
  "parameters": {
    "endpoint": "/mcp"
  },
  "headers": {
    "X-Weather-API-Key": "${credential.api_key}"
  }
}

Step 2: Register an agent

POST /_plugins/_ml/agents/_register
{
  "name": "weather_assistant",
  "type": "conversational",
  "description": "Assistant with access to weather data",
  "llm": {
    "model_id": "your-llm-model-id"
  },
  "tools": [
    {
      "type": "MCPTool",
      "parameters": {
        "connector_id": "<connector_id_from_step_1>"
      }
    }
  ]
}

Step 3: Use the agent

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}

Logs

Monitor MCP connection logs in the Lucenia logs:

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

Common issues

Issue	Possible Cause	Solution
Connection refused	External MCP server is not running	Verify the server is running and accessible
Authentication failed	Invalid credentials	Check credentials and authentication method
Tool not found	Tool not available on external server	Verify tool availability on the MCP server
Timeout errors	Network latency or server slow to respond	Increase timeout settings
405 Method Not Allowed	Server expects different HTTP method	Ensure the external server supports Streamable HTTP

Security considerations

• Credential management: Store API keys and tokens securely using Lucenia's keystore
• Network security: Use HTTPS for all external MCP connections
• Access control: Implement proper role-based access control for MCP-enabled agents
• Audit logging: Monitor and log all external MCP tool invocations

Next steps

• MCP server APIs
• Register MCP tools
• Agent APIs