MCP Integration

The Model Context Protocol (MCP) lets AI assistants like Claude, ChatGPT, and custom agents interact with Retivo using a standard JSON-RPC 2.0 interface.

Use Cases

Why connect an AI assistant to Retivo?

Customer support agents — AI agents can check user status and trigger targeted interventions during support conversations
Sales copilots — Surface activation scores and risk levels to help sales reps prioritize outreach
Internal tools — Build custom AI workflows that react to user lifecycle changes

Endpoint

POST /api/mcp
Authorization: Bearer rt_live_...
Content-Type: application/json

All requests use the JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": { ... }
  }
}

Available Tools

`track_event`

Track a user event from an AI workflow.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "track_event",
    "arguments": {
      "user_id": "user-123",
      "event_name": "ai_task_completed",
      "properties": { "task": "sprint_planning" }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Event \"ai_task_completed\" tracked for user user-123" }]
  }
}

`get_user_status`

Get a user's lifecycle stage, health score, and risk level.

{
  "params": {
    "name": "get_user_status",
    "arguments": { "user_id": "user-123" }
  }
}

Returns lifecycle stage, activation score, risk level, last activity, opt-out and pause status.

`get_recommendations`

Get AI-recommended actions for a specific user.

{
  "params": {
    "name": "get_recommendations",
    "arguments": { "user_id": "user-123" }
  }
}

Runs the full AI evaluation pipeline for a user, returning a structured recommendation with action, playbook, channel, confidence score, and reasoning.

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"action\":\"intervene\",\"playbook\":\"Onboarding Kickstart\",\"channel\":\"email\",\"confidence\":0.82,\"reasoning\":\"User hasn't completed onboarding in 5 days\"}"
    }]
  }
}

`trigger_intervention`

Manually trigger an intervention for a user through a specific channel.

{
  "params": {
    "name": "trigger_intervention",
    "arguments": {
      "user_id": "user-123",
      "playbook_id": "pb_abc",
      "channel": "email"
    }
  }
}

Channels: email, in_app, webhook

`pause_user`

Pause all interventions for a user.

{
  "params": {
    "name": "pause_user",
    "arguments": {
      "user_id": "user-123",
      "reason": "User requested quiet period"
    }
  }
}

`list_playbooks`

List all active playbooks for your tenant.

{
  "params": {
    "name": "list_playbooks",
    "arguments": {}
  }
}

Discovering Tools

To list all available tools programmatically:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Returns tool names, descriptions, and input schemas — compatible with the MCP tool discovery spec.

Error Handling

Errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Unknown tool: invalid_tool"
  }
}

Code	Meaning
`-32600`	Invalid JSON-RPC request
`-32601`	Unknown method or tool

Example: Claude Desktop Integration

Add Retivo to your Claude Desktop MCP config:

{
  "mcpServers": {
    "retivo": {
      "url": "https://retivo.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer rt_live_..."
      }
    }
  }
}

Once connected, Claude can track events, check user status, and trigger interventions on your behalf through natural language.

Example: Cursor Integration

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "retivo": {
      "url": "https://retivo.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer rt_live_..."
      }
    }
  }
}

Example: VS Code (Copilot) Integration

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "retivo": {
        "type": "http",
        "url": "https://retivo.ai/api/mcp",
        "headers": {
          "Authorization": "Bearer rt_live_..."
        }
      }
    }
  }
}

MCP Integration

On this page