MCP Server Integration

Connect AI assistants like Claude directly to your Taruvi data using the Model Context Protocol (MCP).

Overview

Taruvi provides a Model Context Protocol (MCP) server that allows AI assistants to interact with your data in real-time. This enables powerful workflows where Claude can:

• Query your database tables
• Create and update records
• Analyze your data
• Build reports and dashboards
• Automate data operations

What is MCP?

The Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools. Think of it as a standardized API that AI models can use to access your application data.

Key Benefits:

• 🔒 Secure: Authentication with API keys
• 🚀 Real-time: Direct access to live data
• 🎯 Scoped: Access limited to specific apps via App Slug
• 📊 Powerful: Full query, aggregation, and CRUD capabilities
• 🔌 Standard: Works with any MCP-compatible client

---

Quick Start

1. Get Your Credentials

You'll need two pieces of information from the Taruvi Console:

A. Generate an API Key

1. Log in to Taruvi Console
2. Click on your user dropdown (top-right corner)
3. Select "API Keys" or "Settings"
4. Click "Generate New API Key"
5. Copy and save the key - it won't be shown again!

Example API Key:

Api-Key ef5d36343a8e80870f9fc915adf74b5df889129c1554bbb794773427d0db38fd

B. Get Your App Slug

1. In the Taruvi Console, navigate to "Apps"
2. Select your app or create a new one
3. Copy the slug from the app details

Example App Slug: sample-app, blog-app, my-application

C. Find Your Site URL

Your site URL is the domain where your Taruvi instance is hosted:

Examples:

• Production: https://yoursite.taruvi.com
• Local development: http://tenant1.127.0.0.1.nip.io:8000
• Custom domain: https://api.yourcompany.com

---

Configuration

Claude Code (CLI)

Add this configuration to your Claude Code settings file (~/.claude/claude_desktop_config.json or .claude/settings.local.json):

{
  "mcpServers": {
    "taruvi": {
      "type": "sse",
      "url": "https://yoursite.taruvi.com/mcp/sse",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY_HERE",
        "X-App-Slug": "your-app-slug"
      }
    }
  }
}

Example with actual values:

{
  "mcpServers": {
    "taruvi": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Api-Key ef5d36343a8e80870f9fc915adf74b5df889129c1554bbb794773427d0db38fd",
        "X-App-Slug": "blog-app"
      }
    }
  }
}

Local Development Example:

{
  "mcpServers": {
    "taruvi-local": {
      "type": "sse",
      "url": "http://tenant1.127.0.0.1.nip.io:8000/mcp/sse",
      "headers": {
        "Authorization": "Api-Key ef5d36343a8e80870f9fc915adf74b5df889129c1554bbb794773427d0db38fd",
        "X-App-Slug": "sample-app"
      }
    }
  }
}

Claude Desktop App

1. Open Claude Desktop app
2. Go to Settings → Developer → Edit Config
3. Add the same configuration as above
4. Save and restart Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Multiple Environments

You can connect to multiple Taruvi sites or apps:

{
  "mcpServers": {
    "taruvi-production": {
      "type": "sse",
      "url": "https://api.yourcompany.com/mcp/sse",
      "headers": {
        "Authorization": "Api-Key PRODUCTION_API_KEY",
        "X-App-Slug": "production-app"
      }
    },
    "taruvi-staging": {
      "type": "sse",
      "url": "https://staging.yourcompany.com/mcp/sse",
      "headers": {
        "Authorization": "Api-Key STAGING_API_KEY",
        "X-App-Slug": "staging-app"
      }
    },
    "taruvi-local": {
      "type": "sse",
      "url": "http://localhost:8000/mcp/sse",
      "headers": {
        "Authorization": "Api-Key LOCAL_API_KEY",
        "X-App-Slug": "dev-app"
      }
    }
  }
}

---

Available Capabilities

Once connected, Claude can access your Taruvi data through MCP tools and resources:

MCP Tools

Available operations (via MCP tool calls):

1. Query Data

   • List all records with filters
   • Get single record by ID
   • Advanced filtering (20+ operators)
   • Sorting and pagination
   • Relationship population

2. Aggregate Data

   • COUNT, SUM, AVG, MIN, MAX
   • GROUP BY with multiple fields
   • HAVING clause filters
   • Complex analytics

3. Create Data

   • Insert single records
   • Bulk insert
   • Upsert (insert or update)

4. Update Data

   • Update single records
   • Bulk updates
   • Partial updates (PATCH)

5. Delete Data

   • Delete single records
   • Bulk delete by IDs
   • Delete by filter

6. Schema Operations

   • List tables
   • Get table schema
   • Describe fields and relationships

MCP Resources

Available resources (via MCP resource URIs):

• taruvi://tables - List all tables in the app
• taruvi://tables/{table_name} - Get table schema
• taruvi://tables/{table_name}/data - Get table data
• taruvi://stats - Get app statistics

---

Usage Examples

Example 1: Query Blog Posts

Prompt to Claude:

Using the Taruvi MCP server, show me all published blog posts from the last 7 days,
sorted by views (highest first). Include the author information.

What Claude does:

1. Connects to your Taruvi MCP server
2. Queries the posts table with filters:
   • status=published
   • created_at__gte=<7 days ago>
   • populate=author
   • ordering=-views
3. Returns formatted results

Example 2: Create Multiple Records

Prompt to Claude:

Create 5 sample products in my Taruvi store app with realistic data.

What Claude does:

1. Generates realistic product data
2. Uses MCP to bulk insert into products table
3. Returns confirmation with created IDs

Example 3: Analytics Dashboard

Prompt to Claude:

Create a sales dashboard showing:
- Total revenue this month
- Revenue by product category
- Top 5 customers by spend

What Claude does:

1. Runs aggregation queries via MCP:
   • SUM(total) grouped by month
   • SUM(amount) grouped by category
   • SUM(order_total) grouped by customer with HAVING clause
2. Formats results as a dashboard
3. Optionally creates visualizations

Example 4: Data Cleanup

Prompt to Claude:

Find and delete all draft posts older than 30 days that have no comments.

What Claude does:

1. Queries posts with filters:
   • status=draft
   • created_at__lt=<30 days ago>
   • Joins with comments to filter comment_count=0
2. Shows you the matching records
3. Asks for confirmation
4. Deletes via MCP bulk delete

Example 5: Complex Report

Prompt to Claude:

Generate a monthly user engagement report:
- New users per month
- Posts per user
- Average comments per post
- Most active authors

What Claude does:

1. Runs multiple aggregation queries
2. Combines results
3. Formats as markdown report
4. Can export to CSV if requested

---

Security Best Practices

1. API Key Management

✅ DO:

• Store API keys in config files, never in code
• Use different API keys for different environments
• Rotate API keys regularly
• Revoke unused keys immediately

❌ DON'T:

• Commit API keys to version control
• Share API keys in chat/email
• Use production keys in development
• Leave old keys active

2. App Scope

The X-App-Slug header limits MCP access to a specific app. This means:

• Claude can only access tables in that app
• No cross-app data access
• Easy to control what data is accessible

Tip: Create a dedicated "analytics-app" or "ai-app" for MCP access with only the tables you want Claude to query.

3. Permissions

MCP respects your Taruvi authorization policies:

• Row-level security still applies
• API key permissions determine access
• Use restrictive policies for MCP access

Example: Create a read-only API key for analytics:

{
  "name": "MCP Analytics (Read-only)",
  "permissions": ["read"],
  "apps": ["analytics-app"]
}

---

Troubleshooting

Connection Failed

Error: "Cannot connect to MCP server"

Solutions:

1. Verify the URL is correct and accessible
2. Check if the site is running: curl https://yoursite.taruvi.com/health/
3. Ensure /mcp/sse endpoint exists
4. Check firewall/network settings

Authentication Failed

Error: "401 Unauthorized" or "Invalid API key"

Solutions:

1. Verify API key format: Must be Api-Key <your-key> (not Bearer)
2. Check for extra spaces in the key
3. Regenerate API key in console
4. Ensure API key hasn't been revoked

App Not Found

Error: "404 Not Found" or "App does not exist"

Solutions:

1. Verify X-App-Slug matches exactly (case-sensitive)
2. Check app exists in Taruvi Console
3. Ensure you have access to the app

Table Not Found

Error: "Table 'users' does not exist"

Solutions:

1. Check table name spelling (case-sensitive)
2. Ensure table is materialized: POST /api/apps/{slug}/datatables/{name}/materialize/
3. Verify table is in the correct app

Slow Responses

Problem: MCP queries taking too long

Solutions:

1. Add indexes to frequently queried fields
2. Use pagination for large datasets
3. Limit relationship population
4. Use aggregations instead of fetching all data

CORS Errors (Browser-based clients)

Error: "CORS policy blocked"

Solutions:

1. MCP server is designed for server-to-server or desktop clients
2. For browser usage, ensure CORS is configured in Taruvi settings
3. Use Claude Desktop or Claude Code instead of web clients

---

Advanced Configuration

Custom Timeout

{
  "mcpServers": {
    "taruvi": {
      "type": "sse",
      "url": "https://yoursite.taruvi.com/mcp/sse",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY",
        "X-App-Slug": "your-app"
      },
      "timeout": 30000
    }
  }
}

Proxy Configuration

{
  "mcpServers": {
    "taruvi": {
      "type": "sse",
      "url": "https://yoursite.taruvi.com/mcp/sse",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY",
        "X-App-Slug": "your-app"
      },
      "proxy": "http://proxy.company.com:8080"
    }
  }
}

Environment-Specific Config

Use environment variables in Claude Code:

{
  "mcpServers": {
    "taruvi": {
      "type": "sse",
      "url": "${TARUVI_MCP_URL}",
      "headers": {
        "Authorization": "Api-Key ${TARUVI_API_KEY}",
        "X-App-Slug": "${TARUVI_APP_SLUG}"
      }
    }
  }
}

Set in your shell:

export TARUVI_MCP_URL="https://yoursite.taruvi.com/mcp/sse"
export TARUVI_API_KEY="your-api-key-here"
export TARUVI_APP_SLUG="your-app-slug"

---

Use Cases

1. Data Analysis & Reports

Ask Claude to analyze your data:

• "What are our top 10 products by revenue this quarter?"
• "Show me user growth month-over-month"
• "Find anomalies in our sales data"

2. Data Entry & Import

Use Claude to populate your database:

• "Create 20 sample users for testing"
• "Import this CSV data into the products table"
• "Generate realistic test data for my e-commerce app"

3. Data Cleanup

Let Claude help maintain data quality:

• "Find and merge duplicate customer records"
• "Delete test data created before January 1st"
• "Identify incomplete user profiles"

4. Monitoring & Alerts

Query for issues in real-time:

• "Are there any failed orders in the last hour?"
• "Show me users who haven't logged in for 90 days"
• "Find posts with inappropriate content flags"

5. Documentation & Schema Discovery

Explore your data structure:

• "What tables are in my app?"
• "Describe the schema for the users table"
• "Show me all relationships in my database"

6. Complex Queries

Build queries you'd normally write SQL for:

• "Join users with their orders and calculate average order value per user"
• "Find posts with more than 100 likes but less than 5 comments"
• "Get monthly active users segmented by signup date cohort"

---

API Endpoints Reference

MCP SSE Endpoint

GET /mcp/sse

Headers Required:

• Authorization: Api-Key <your-api-key>
• X-App-Slug: <your-app-slug>

Protocol: Server-Sent Events (SSE)

Response: JSON-RPC 2.0 messages

Health Check

curl https://yoursite.taruvi.com/mcp/sse \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "X-App-Slug: your-app"

Expected: SSE stream connection established

---

Migration Guide

From Direct API to MCP

If you're currently using the Taruvi REST API directly, MCP provides several advantages:

Before (Direct API):

const response = await fetch('https://api.example.com/api/apps/blog/datatables/posts/data/?status=published', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

After (via Claude + MCP): Simply ask Claude:

Show me all published posts from the blog app

Claude uses MCP behind the scenes to fetch the data with the same API, but you don't need to write code!

---

Next Steps

Learn More About MCP

• Model Context Protocol Docs
• Claude MCP Guide
• MCP GitHub Repository

Explore Taruvi Features

• Data Service API - What data operations are available
• CRUD Operations - How to create, read, update, delete
• Aggregations - Analytics and reporting
• Querying Guide - Advanced filtering
• Authorization - Security and access control

Build Something

Try these projects with Claude + MCP:

1. Analytics Dashboard: Ask Claude to analyze your data and create reports
2. Data Migration: Use Claude to transform and import data
3. Quality Assurance: Have Claude check for data inconsistencies
4. Automated Reports: Schedule Claude to generate weekly/monthly reports

---

Support

Get Help

• 📚 Documentation
• 💬 Community Forum
• 📧 Support Email
• 🐛 Report Issues

Feedback

We'd love to hear about your MCP use cases! Share your experience:

• What are you building with Claude + Taruvi MCP?
• What features would make it more useful?
• Any pain points or suggestions?

---

Happy building! 🚀