MCP Integration

This guide is designed for developers looking to create a custom chat agent—not tied to a specific platform—that can query and execute tools using Caddey’s Model Context Protocol (MCP). Whether you’re building a web-based chatbot, a customer support assistant, or an internal automation tool, these steps will help you seamlessly integrate Caddey’s MCP capabilities into your custom solution.

Prerequisites

• Caddey Account: Ensure you have an active Caddey account with at least one Agent created.
• API Key: Copy the Agent’s API key from https://app.caddey.ai → Agents.
• Development Environment: Familiarity with JSON-RPC, Server-Sent Events (SSE), and HTTP clients (e.g., curl or your preferred library).

Step 1: Configure Your Agent API Key

1. Log in to Caddey at https://app.caddey.ai.
2. Navigate to the Agents tab.
3. Select your Agent and copy the API Key.
4. In your assistant’s configuration, store this key for use as the X-API-KEY header on all MCP requests.

Step 2: Open the SSE Stream & Read Endpoint URL

Establish a persistent SSE connection to receive all JSON-RPC messages (responses and notifications):

curl -N -X GET \
  -H "Accept: text/event-stream" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  https://api.caddey.ai/mcp

The server will respond with Content-Type: text/event-stream and push an initial SSE event named endpoint with the full POST URL (including the sessionId query parameter). For example:

event: endpoint
data: /mcp?sessionId=123e4567-e89b-12d3-a456-426655440000

Note the sessionId in the URL; you will use this query parameter on all subsequent POST requests. Keep the SSE connection open; the server will push tool listings, invocation results, and notifications here.

Step 3: Initialization Handshake

Before calling tools, perform the required JSON-RPC initialization over POSTs to the URL from the endpoint event.

3a. Send initialize

curl -X POST "https://api.caddey.ai/mcp?sessionId=<SESSION_ID>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2024-11-05",
        "clientInfo": {
          "name": "my-agent",
          "version": "1.0.0"
        },
        "capabilities": {
          "notifications": true
        }
      }
    }'

The server will reply on your SSE stream with a JSON-RPC response containing its protocol version and capabilities.

3b. Send notifications/initialized Notification

Acknowledge the handshake (no SSE response expected):

curl -X POST "https://api.caddey.ai/mcp?sessionId=<SESSION_ID>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
      "jsonrpc": "2.0",
      "method": "notifications/initialized",
      "params": {}
    }'

Step 4: Discover Available Tools

Request the full list of tools:

curl -X POST "https://api.caddey.ai/mcp?sessionId=<SESSION_ID>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/list",
      "params": {}
    }'

The SSE event will include a "tools" array containing all available tool definitions.

Step 5: Invoke a Tool

Call any listed tool by name, passing its arguments:

curl -X POST "https://api.caddey.ai/mcp?sessionId=<SESSION_ID>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
      "jsonrpc": "2.0",
      "id": 3,
      "method": "tools/call",
      "params": {
        "name": "translateText",
        "arguments": {
          "source": "en",
          "target": "es",
          "text": "Good morning"
        }
      }
    }'

The result will arrive on your SSE stream with the same id.

Step 6: Handle Notifications & Reconnects

• Tool-list changes:
  The server may send a notifications/tools/list_changed notification. On receipt, re-run tools/list to refresh your cache.

• SSE reconnect:
  If your SSE connection drops, re-open it using the Last-Event-ID header to resume from the last event:

  curl -N -X GET \
    -H "Accept: text/event-stream" \
    -H "X-API-KEY: <YOUR_API_KEY>" \
    -H "Last-Event-ID: <LAST_EVENT_ID>" \
    https://api.caddey.ai/mcp
  

  You do not need to re-run the JSON-RPC handshake unless the server’s protocol version changes.

Step 7: Finalize and Deploy

1. Review Your Integration: Test reconnect logic, error cases (isError responses), and invalid inputs.
2. Deploy Your Chat Agent: Package your MCP logic into your service or client.
3. Monitor Usage: Use Caddey’s dashboard and logs to track calls, errors, and performance.

Additional Resources

• MCP Specification: https://modelcontextprotocol.io