MCP integration

Learn how to leverage Caddey's Model Context Protocol (MCP) endpoint to access and execute a range of tools.

This guide is designed for developers looking to create a custom AI 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.

Security Notice: When implementing MCP integration, ensure your client validates server certificates and implements proper authentication. If running locally during development, bind only to localhost (127.0.0.1) to prevent potential security issues.

Prerequisites

Caddey Account: Ensure you have an active Caddey account with at least one Confidential OAuth client created.
OAuth Access Token: Obtain an access token through OAuth 2.0 flow with your Caddey client.
Development Environment: Familiarity with JSON-RPC and HTTP clients (e.g., curl or your preferred library).

Step 1: Authentication

Create a Confidential OAuth client in Caddey and obtain the Client ID and Client Secret.
Perform the OAuth 2.0 flow to get an access token.
Include Authorization: Bearer <ACCESS_TOKEN> on all MCP requests.

Step 2: Complete the JSON-RPC Handshake

2a. Send `initialize`

curl -X POST "https://api.caddey.ai/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-06-18",
        "capabilities": {},
        "clientInfo": {
          "name": "my-custom-assistant",
          "version": "1.0.0"
        }
      }
    }'

The server responds with an initialize result containing its capabilities. If the server returns an Mcp-Session-Id header, you must include this session ID in all subsequent requests.

2b. Send `notifications/initialized`

Acknowledge the handshake (server responds with HTTP 202 Accepted):

curl -X POST "https://api.caddey.ai/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Mcp-Session-Id: <SESSION_ID_FROM_INITIALIZE_RESPONSE>" \
  -d '{
      "jsonrpc": "2.0",
      "method": "notifications/initialized",
      "params": {}
    }'

Step 3: List Available Tools

Request the full list of tools:

curl -X POST "https://api.caddey.ai/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Mcp-Session-Id: <SESSION_ID_FROM_INITIALIZE_RESPONSE>" \
  -d '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/list",
      "params": {}
    }'

Step 4: Execute Tools

Call any listed tool by name, passing its arguments:

curl -X POST "https://api.caddey.ai/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Mcp-Session-Id: <SESSION_ID_FROM_INITIALIZE_RESPONSE>" \
  -d '{
      "jsonrpc": "2.0",
      "id": 3,
      "method": "tools/call",
      "params": {
        "name": "send_email",
        "arguments": {
          "to": "[email protected]",
          "subject": "Hello from Caddey",
          "body": "This email was sent via MCP!"
        }
      }
    }'

Step 5: Handle responses

The server may return either application/json (single response) or text/event-stream (SSE) for streaming.
Match responses using the JSON-RPC id you sent.
If the initialize response includes an Mcp-Session-Id header, include it on subsequent requests. If you receive HTTP 404, start a new session and reinitialize.

Additional Resources

Semantic Kernel API integration