Karini MCP Server

MCP (Model Context Protocol) server for integrating Karini AI copilots, webhook recipes, and dataset search.

Features

• 🤖 AI Copilot Integration - Ask questions and get AI-powered responses from your Karini copilots
• 📄 Document Processing - Process documents stored in S3 through copilots and webhooks
• 🔗 Webhook Recipes - Trigger asynchronous data processing workflows
• 📊 Status Tracking - Monitor webhook execution status and results
• 🔍 Dataset Search - Query your Karini knowledge base with semantic search
• 🔎 Event Tracing - Trace and debug Karini events by request ID

Installation

Via uvx (Recommended)

uvx karini-mcp-server

Via pip

pip install karini-mcp-server

Configuration

Claude Desktop Setup

Edit your Claude Desktop configuration file:

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

Full Configuration (All Features)

{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "KARINI_COPILOT_ID": "karini-copilot-id",
        "KARINI_API_KEY": "karini-api-key",
        "WEBHOOK_API_KEY": "karini-webhook-api-key",
        "WEBHOOK_RECIPE_ID": "karini-webhook-recipe-id",
        "KARINI_DATASET_ID": "karini-dataset-id"
      }
    }
  }
}

Copilot Only Configuration

{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "KARINI_COPILOT_ID": "karini-copilot-id",
        "KARINI_API_KEY": "karini-api-key"
      }
    }
  }
}

Webhook Only Configuration

{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "WEBHOOK_API_KEY": "karini-webhook-api-key",
        "WEBHOOK_RECIPE_ID": "karini-webhook-recipe-id"
      }
    }
  }
}

Dataset Search Only Configuration

{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "KARINI_API_KEY": "karini-api-key",
        "KARINI_DATASET_ID": "karini-dataset-id"
      }
    }
  }
}

Note: Only tools with valid configuration will be available. Configure only the features you need.

Environment Variables

Variable	Required For	Description
KARINI_API_BASE	All	Base URL for Karini API (e.g., https://app.karini.ai)
KARINI_API_KEY	Copilot, Dataset, Tracing	API key for authentication
KARINI_COPILOT_ID	Copilot	Your copilot's unique identifier
KARINI_DATASET_ID	Dataset	Your dataset's unique identifier
WEBHOOK_API_KEY	Webhook	API key for webhook authentication
WEBHOOK_RECIPE_ID	Webhook	Webhook recipe identifier

Available Tools

Copilot Tools

ask_karini_copilot

Ask questions to your Karini AI copilot and receive intelligent responses.

Parameters:

• question (string, required): The question or query to ask
• files (list, optional): S3 file paths to include in the query
  • Example: ["s3://bucket/document.pdf", "s3://bucket/data.txt"]

Webhook Tools

invoke_webhook_recipe

Trigger a webhook recipe for asynchronous data processing.

Parameters:

• question (string, optional): Input message or query
• files (list, optional): S3 file paths to process (content type auto-detected)
  • Example: ["s3://bucket/invoice.pdf", "s3://bucket/receipt.jpg"]
• metadata (dict, optional): Additional context as key-value pairs
  • Example: {"user_id": "123", "priority": "high", "source": "email"}

Returns: JSON with request_id for status tracking

get_webhook_status

Check the status of webhook recipe executions.

Parameters:

• request_id (string, optional): Specific request ID to check. If not provided, returns recent requests.
• limit (integer, optional): Number of recent requests to return (default: 5)

Dataset Tools

query_karini_dataset

Search and retrieve information from your Karini knowledge base using semantic search.

Parameters:

• text (string, required): The search query or question
• top_k (integer, optional): Number of results to return (default: 5, max: 20)

Tracing Tools

get_traces

Trace and retrieve detailed information about a specific Karini event using its request ID.

Parameters:

• request_id (string, required): The unique identifier of the Karini event to trace

Returns: Detailed trace information including execution steps, timing, and debug data

Examples:

Trace event "67309a4f8b1c2d3e4f5a6b7c"

Get traces for request ID "abc123def456"

Development

Local Testing

# Clone repository
git clone https://github.com/yourusername/karini-mcp-server.git
cd karini-mcp-server

# Install dependencies
pip install -e .

# Run locally
python -m src.main

Project Structure

karini-mcp-server/
├── src/
│   ├── main.py              # Entry point
│   ├── server.py            # MCP server setup
│   ├── services/
│   │   ├── config.py        # Configuration management
│   │   └── client.py        # Karini API client
│   └── tools/
│       └── tools.py         # Tool definitions
├── pyproject.toml
└── README.md