Opensure

Appearance

Opensure MCP Quickstart Guide ​

Welcome to Opensure MCP! This guide will walk you through setting up the Opensure Model Context Protocol (MCP) server to manage insurance clients and policies directly from Claude Desktop.

What is Opensure MCP? ​

Opensure MCP is a Model Context Protocol server that enables AI assistants like Claude to interact with your insurance CRM data. Think of it as "the HTTP of insurance operations" – a foundational protocol for AI-powered insurance workflows.

Key Features ​

  • 🔐 Multi-tenant isolation – Your data stays completely separate from other brokers
  • 🗄️ Your own database – Data stored in your Supabase (PostgreSQL) instance
  • 🔑 Secure authentication – API key-based access with bcrypt hashing
  • 📊 Full CRUD operations – Create, read, update, and list clients and policies
  • 🚀 Serverless-ready – Optimized for Vercel and serverless deployments

Prerequisites ​

Before you begin, you'll need:

Step 1: Create Your Opensure Account ​

  1. Go to https://app.opensure.dev/signup
  2. Enter your email and create a password
  3. Verify your email address (check your inbox for verification code)
  4. Log in to your dashboard

Note: Your tenant ID is automatically created during signup. This isolates your data from other users.

Step 2: Generate Your API Key ​

API keys authenticate the MCP server with your Opensure account.

From the Dashboard: ​

  1. Navigate to Settings → API Keys (/api-keys)
  2. Click "Create New Key"
  3. Select scope:
    • Read + Write (Recommended) – Full access to create and update data
    • Read Only – Query data only, no modifications
  4. Click "Generate Key"
  5. ⚠️ IMPORTANT: Copy the key immediately – it's shown only once!

Your API Key Format: ​

osk_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Prefix: osk_ (Opensure Key)
  • First segment: 8 random characters (visible in dashboard)
  • Second segment: 48 random characters (secret)

Security Notes: ​

  • ✅ Keys are hashed with bcrypt (plaintext never stored)
  • ✅ Keys are tenant-scoped (can only access your data)
  • ✅ Keys can be revoked anytime from the dashboard
  • ❌ Never commit keys to git or share publicly

Step 3: Set Up Your Supabase Database ​

Opensure MCP stores data in your own Supabase PostgreSQL database.

3.1 Create a Supabase Project ​

  1. Go to https://supabase.com/dashboard
  2. Click "New Project"
  3. Fill in project details:
    • Name: opensure-mcp (or your choice)
    • Database Password: Choose a strong password (save it!)
    • Region: Select closest to you
  4. Click "Create new project" (takes ~2 minutes)

3.2 Get Your Database Connection URL ​

  1. In your Supabase project, go to Settings → Database
  2. Scroll to "Connection string"
  3. Select "Connection pooling" tab (recommended for serverless)
  4. Copy the URI format:
postgresql://postgres.xxxxxxxxxxxxx:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:6543/postgres
  1. Replace [YOUR-PASSWORD] with your actual database password

Why pooled connection?

  • ✅ Better for serverless environments (Vercel, AWS Lambda)
  • ✅ Handles connection limits automatically
  • ✅ Faster cold starts

3.3 Configure Database in Opensure Dashboard ​

  1. Navigate to Settings → Database (/database)
  2. Paste your connection URL
  3. Select "Pooled" connection type
  4. Click "Test Connection" to verify
  5. Click "Save Configuration" once test passes

Step 4: Run Database Migrations ​

The MCP server needs database tables for clients and policies. Run the migration command to set up your schema.

4.1 Run Migration Command ​

Open your terminal and run:

bash
npx @opensure/mcp-migrate --api-key=osk_xxx --database-url=postgresql://...

Parameters:

  • --api-key – Your Opensure API key (from Step 2)
  • --database-url – Your Supabase connection URL (from Step 3.2)

4.2 What Gets Created ​

The migration creates two tables in your Supabase database:

mcp_clients table:

  • uuid (primary key)
  • tenant_id (your isolation key)
  • name, email, phone, address
  • created, modified timestamps
  • Indexes on (tenant_id, created)

mcp_policies table:

  • uuid (primary key)
  • tenant_id (your isolation key)
  • client_uuid (foreign key to clients)
  • policy_number (auto-generated: POL-{tenant_prefix}-{counter})
  • 40 fields total (coverage, premiums, dates, etc.)
  • Indexes on (tenant_id, created), (tenant_id, policy_number)

schema_migrations table:

  • Tracks applied migrations (ensures idempotency)
  • Re-running migrations is safe – already-applied migrations are skipped

4.3 Verify in Supabase ​

  1. Go to Supabase → Table Editor
  2. You should see 3 new tables:
    • mcp_clients
    • mcp_policies
    • schema_migrations

Step 5: Configure Claude Desktop ​

Now let's connect Claude Desktop to your Opensure MCP server.

5.1 Locate Claude Config File ​

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

5.2 Add Opensure MCP Server ​

Edit the config file and add the Opensure MCP server:

json
{
  "mcpServers": {
    "opensure": {
      "command": "npx",
      "args": ["-y", "@opensure/mcp-server-stdio"],
      "env": {
        "OPENSURE_API_KEY": "osk_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // pragma: allowlist secret
        "DATABASE_URL": "postgresql://postgres.xxxxxxxxxxxxx:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:6543/postgres"
      }
    }
  }
}

Replace:

  • OPENSURE_API_KEY with your actual API key (from Step 2)
  • DATABASE_URL with your Supabase connection URL (from Step 3.2)

5.3 Restart Claude Desktop ​

  1. Quit Claude Desktop completely
  2. Relaunch Claude Desktop
  3. Look for the 🔌 MCP icon in the bottom-right
  4. You should see "opensure" listed as a connected server

Step 6: Create Your First Client ​

Let's test the MCP server by creating a client record.

6.1 Ask Claude to Create a Client ​

In Claude Desktop, type:

Create a new insurance client named "Apex Manufacturing Ltd" with email [email protected] and phone 416-555-0123

6.2 What Happens Behind the Scenes ​

  1. Claude calls client.create tool with your parameters
  2. MCP server validates API key via Opensure backend
  3. Tenant ID extracted from validated API key
  4. Record inserted into mcp_clients table in your Supabase
  5. UUID auto-generated for the client
  6. Response returned to Claude with client details

6.3 Expected Response ​

Claude will respond with something like:

✓ Client created successfully!

Client Details:
- Name: Apex Manufacturing Ltd
- UUID: 01HTABC123XYZ456789...
- Email: [email protected]
- Phone: 416-555-0123
- Created: 2025-10-27T15:30:00Z

Step 7: Verify in Supabase ​

Let's confirm the data was actually saved to your database.

7.1 View in Supabase Table Editor ​

  1. Go to Supabase → Table Editor
  2. Click on mcp_clients table
  3. You should see your new client record:
uuidtenant_idnameemailphonecreated
01HT...your_tenant_idApex Manufacturing Ltd[email protected]416-555-01232025-10-27...

7.2 Verify Tenant Isolation ​

Notice the tenant_id column – this ensures your data is isolated from other users. Even if someone else creates a client with the same name, they'll have a different tenant_id.

Next Steps ​

🎉 Congratulations! You've successfully set up Opensure MCP. Here's what you can do next:

Available MCP Tools ​

Client Management:

  • client.create – Create a new client
  • client.get – Retrieve client by UUID
  • client.list – List all clients (paginated, sorted by created DESC)
  • client.update – Update client details

Policy Management:

  • policy.create – Create a new policy (auto-generates policy number)
  • policy.get – Retrieve policy by UUID
  • policy.list – List all policies (paginated, supports status filter)
  • policy.update – Update policy status, premium, coverage, etc.

Example Commands ​

List all clients:

Show me all my insurance clients

Create a policy:

Create a General Liability policy for client UUID 01HTABC123... with $2,000,000 coverage limit and $3,500 annual premium

Update a client:

Update client 01HTABC123... to add address "123 Main St, Toronto, ON M5V 3A8"

Search policies:

Show me all active policies with premium over $5,000

Troubleshooting ​

MCP Server Not Showing in Claude Desktop ​

Symptoms:

  • No 🔌 icon in bottom-right of Claude Desktop
  • "opensure" server not listed

Solutions:

  1. Verify claude_desktop_config.json syntax is valid JSON
  2. Check file path is correct for your OS
  3. Restart Claude Desktop completely (quit and relaunch)
  4. Check Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/mcp*.log
    • Windows: %APPDATA%\Claude\logs\mcp*.log

API Key Validation Failed ​

Symptoms:

  • Error: "Invalid API key" or "Authentication failed"

Solutions:

  1. Verify API key copied correctly (no extra spaces)
  2. Check key is active in dashboard (Settings → API Keys)
  3. Ensure key has correct scope (write access needed for create operations)
  4. Generate a new key if needed

Database Connection Failed ​

Symptoms:

  • Error: "Connection refused" or "Connection timeout"

Solutions:

  1. Verify database URL copied correctly
  2. Check password replaced [YOUR-PASSWORD] placeholder
  3. Test connection in dashboard (Settings → Database → Test Connection)
  4. Verify Supabase project is not paused (free tier pauses after inactivity)
  5. Check Supabase project region matches connection string

Migration Already Applied ​

Symptoms:

  • Migration command says "Already applied"

Solutions:

  • This is normal – migrations are idempotent
  • If you need to re-apply, manually delete from schema_migrations table
  • Or start fresh by dropping all MCP tables (⚠️ deletes data!)

Tenant ID Mismatch ​

Symptoms:

  • Can't see records you created
  • "No records found" when you know they exist

Solutions:

  1. Verify using same API key that created the records
  2. Check tenant_id in Supabase matches your API key's tenant
  3. Each API key is tied to one tenant – switching keys changes data visibility

Security Best Practices ​

API Key Management ​

✅ DO:

  • Store keys in environment variables or secure vaults
  • Use different keys for development vs production
  • Revoke compromised keys immediately
  • Rotate keys periodically (every 90 days)

❌ DON'T:

  • Commit keys to git repositories
  • Share keys in public channels
  • Use same key across multiple environments
  • Store keys in plaintext files

Database Security ​

✅ DO:

  • Use connection pooling for production
  • Enable Row-Level Security (RLS) in Supabase (optional extra layer)
  • Regularly backup your Supabase database
  • Monitor database connection limits

❌ DON'T:

  • Use direct connections in serverless environments
  • Share database credentials
  • Expose database publicly without firewall rules

Architecture Overview ​

┌─────────────────┐
│  Claude Desktop │
│                 │
│  User: "Create │
│   client Acme" │
└────────┬────────┘
         │
         │ MCP Protocol (stdio)
         │
         ▼
┌─────────────────────────┐
│  @opensure/mcp-server   │
│  (Running via npx)      │
│                         │
│  1. Validate API key    │────┐
│  2. Extract tenant_id   │    │
│  3. Execute query       │    │
└────────┬────────────────┘    │
         │                     │
         │                     │ HTTPS
         ▼                     │
┌─────────────────────────┐    │
│  Your Supabase DB       │    │
│  (PostgreSQL)           │    │
│                         │    │
│  - mcp_clients          │    │
│  - mcp_policies         │    │
│  - schema_migrations    │    │
└─────────────────────────┘    │
                               │
                               ▼
                    ┌──────────────────────┐
                    │  api.opensure.dev │
                    │  (Django REST API)   │
                    │                      │
                    │  Validates API keys  │
                    │  Returns tenant_id   │
                    └──────────────────────┘

Data Flow ​

  1. User types command in Claude Desktop
  2. Claude identifies tool to use (e.g., client.create)
  3. MCP server receives request via stdio transport
  4. API key validated with Opensure backend
  5. Tenant ID extracted from validation response
  6. Query executed with automatic tenant_id filtering
  7. Results returned to Claude
  8. Claude formats response for user

Multi-Tenancy Enforcement ​

Every database query automatically includes WHERE tenant_id = $1:

sql
-- Example client.list query
SELECT * FROM mcp_clients
WHERE tenant_id = $1  -- Your tenant ID injected automatically
ORDER BY created DESC
LIMIT 100;

This ensures you can ONLY access your own data, even if another user has records with the same name or email.

Support & Resources ​

Documentation ​

Community ​

Changelog ​

  • v2.0.0 – Multi-tenant architecture, Supabase support, dashboard UI
  • v1.0.0 – Initial MCP server release

Frequently Asked Questions ​

Q: Is my data stored in Opensure's servers? ​

A: No! Your client and policy data is stored in your own Supabase database. Opensure only stores:

  • Your account credentials (email, hashed password)
  • API key metadata (prefix, hash, tenant ID)
  • Database connection settings (connection URL)

Q: Can other users see my data? ​

A: No. Every query is automatically filtered by tenant_id, ensuring complete isolation between tenants. Even Opensure admins cannot see your client/policy data without your Supabase credentials.

Q: What happens if I delete my Supabase project? ​

A: Your MCP server will stop working (connection errors). Your Opensure account remains active. You can create a new Supabase project, update the connection settings, and re-run migrations.

Q: Can I use a different database (not Supabase)? ​

A: Currently, only PostgreSQL via Supabase is supported. Support for other PostgreSQL providers (AWS RDS, Google Cloud SQL) is planned for v2.1.

Q: How much does Opensure MCP cost? ​

A: Opensure has a free tier for development and small teams. Check opensure.dev/pricing for current plans. Supabase also has a generous free tier (500MB database, 2GB bandwidth).

Q: Can I self-host the MCP server? ​

A: The MCP server is distributed via npm and runs locally on your machine (via npx). There's nothing to self-host – it's already client-side. The Django backend (API key validation) is hosted by Opensure.

Happy building! 🚀

Last updated: October 2025

Built with VitePress

Copyright © 2025 Opensure