npm package: @rootplatform/mcp-server
Description: Root Insurance MCP Server - AI tools for insurance quotes, policies, and management
Author: Root Insurance
Latest version: 1.4.1

# Root Insurance MCP Server

A Model Context Protocol (MCP) server that provides AI models with comprehensive Root Insurance tools for creating quotes, managing policies, and handling the complete insurance workflow.

## Installation

Install globally via npm:

```bash
npm install -g @root-platform/mcp-server
```

## Prerequisites

1. **Root Insurance API Key** - Get your API key from [Root Platform](https://root.co.za/)
2. **Node.js 18+** - Required for running the MCP server
3. **MCP-compatible AI client** - Such as Claude Desktop, or any client supporting MCP

## Configuration

When using this MCP server, you need to pass two environment variables through your MCP client. Contact Root Insurance to get your organization's specific endpoint URL.

**Required Environment Variables:**

- `ROOT_INSURANCE_API_KEY` - Your Root Insurance API key
- `ROOT_BASE_URL` - Your Root Insurance endpoint (e.g., `https://staging-sandbox.root.co.za` or `https://sandbox.rootplatform.com`)

### Claude Desktop Configuration

Add to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "root-insurance": {
      "command": "root-mcp",
      "env": {
        "ROOT_INSURANCE_API_KEY": "sandbox_your_api_key_here",
        "ROOT_BASE_URL": "https://staging-sandbox.root.co.za"
      }
    }
  }
}
```

## Available Tools

The MCP server provides these insurance tools to AI models:

### Core Workflow (5-Step Process)

1. **`get-product-modules`** - Discover available insurance products
2. **`get-product-module-schema`** - Get required fields for quotes
3. **`create-quote`** - Generate personalized insurance quotes
4. **`create-policyholder`** - Set up customer profiles
5. **`create-application`** - Submit insurance applications
6. **`issue-policy`** - Convert applications to active policies

## Usage Examples

### With Claude Desktop

Once configured, you can ask Claude:

```
"Create a gadget insurance quote for a R15,000 iPhone in South Africa"

"Help me issue a funeral policy for a 35-year-old with R50,000 cover"

"Show me available Root Insurance products and their requirements"
```

### Programmatic Usage

When using this MCP server in your own applications, pass the environment variables through the transport:

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Your application's configuration
const config = {
  rootApiKey: process.env.ROOT_INSURANCE_API_KEY,
  baseUrl: process.env.ROOT_BASE_URL || "https://sandbox.rootplatform.com/",
};

const transport = new StdioClientTransport({
  command: "root-mcp",
  env: {
    ROOT_INSURANCE_API_KEY: config.rootApiKey,
    ROOT_BASE_URL: config.baseUrl,
  },
});

const client = new Client({ name: "my-insurance-app", version: "1.0.0" });
await client.connect(transport);

// Example: Create a complete insurance policy
async function createInsurancePolicy() {
  // 1. Get available products
  const products = await client.callTool({
    name: "get-product-modules",
    arguments: {
      apiKey: config.rootApiKey,
    },
  });

  // 2. Get schema to understand required fields
  const schema = await client.callTool({
    name: "get-product-module-schema",
    arguments: {
      apiKey: config.rootApiKey,
      productModule: "root_funeral",
      schemaType: "quote",
    },
  });

  // 3. Create a quote with correct field structure
  const quote = await client.callTool({
    name: "create-quote",
    arguments: {
      apiKey: config.rootApiKey,
      productModule: "root_funeral",
      quoteData: {
        first_name: "John",
        last_name: "Doe",
        age: 35,
        cover_amount: 50000,
        // ... other fields based on schema
      },
    },
  });

  // 4. Create policyholder, application, and issue policy
  // ... continue with the workflow
}
```

> **Note**: The MCP server automatically uses the `ROOT_INSURANCE_API_KEY` from the environment, so you don't need to pass it in tool arguments.

### Direct Command Line Usage

If you need to run the MCP server directly (not common), you must provide all environment variables:

```bash
ROOT_INSURANCE_API_KEY=sandbox_your_key \
ROOT_BASE_URL=https://staging-sandbox.root.co.za \
root-mcp
```

The server will validate these variables on startup and exit with a helpful error message if any are missing.

## API Key Types

- **Sandbox keys** (`sandbox_...`) - For testing and development
- **Production keys** (`production_...`) - For live insurance operations

The MCP automatically detects the environment from your API key prefix. All requests use the `ROOT_BASE_URL` endpoint you configured.

## Support

- **Documentation:** [Root Platform Docs](https://docs.rootplatform.com/)
- **API Reference:** [Root Insurance API](https://docs.rootplatform.com/reference)
- **Issues:** [GitHub Issues](https://github.com/root-insurance/mcp-server/issues)

## License

MIT License - see LICENSE file for details.

---

Built by [Root Insurance](https://root.co.za/) - The leading insurtech platform for embedded insurance solutions.