mcp-server

# Kubit MCP Server

**Warehouse-native analytics meets conversational AI**

Bring the full power of Kubit directly into your AI workflow. Query, analyze, and explore your data warehouse through natural language—no complex syntax required.

---

## What is Kubit MCP?

The Kubit MCP (Model Context Protocol) server transforms how teams interact with their analytics platform. By connecting your AI assistant to Kubit, you can:

- **Explore schemas** - Discover events, properties, and dimensions in natural language
- **Generate reports** - Create analytical queries through conversation
- **Export data** - Pull raw data in CSV format for deep analysis  
- **Search content** - Find existing reports and dashboards instantly
- **Ask questions** - Get insights without learning query syntax

> **Beta Notice**
> 
> This server is under active development. You may encounter bugs, performance issues, or rate limits as we continue to improve the platform.

---

## Quick Start

### What You'll Need

| Requirement | Description |
|-------------|-------------|
| **Kubit Account** | Active access to a Kubit organization |
| **AI Client** | MCP-compatible tool (Claude, Cursor, etc.) |
| **Permissions** | Schema access in your Kubit workspace |

### Connection Steps

Setting up the Kubit MCP server is straightforward:

1. **Add the MCP server** to your AI client configuration
2. **Use the server URL**: `https://mcp.kubit.ai/mcp`
3. **Complete OAuth authentication** when prompted
4. **Start querying** your Kubit data

> **Note:** Check your AI client's documentation for specific MCP server setup instructions.

### Authentication & Access

The server uses **OAuth 2.0** authentication and respects your existing Kubit permissions. You'll only see data from schemas you already have access to—no additional permissions needed.

---

## Tools & Capabilities

Your AI assistant gains access to five powerful tools:

| Tool | Purpose |
|------|---------|
| **`getUserContext`** | Initialize session and retrieve available schemas |
| **`getSchema`** | Explore events, properties, and dimensions in detail |
| **`createReport`** | Generate and execute analytical queries |
| **`getRawData`** | Export CSV data from existing reports |
| **`searchKubit`** | Find reports and dashboards across your org |

---

## Example Conversations

### Understanding User Behavior

```
"Show me conversion funnel for mobile app sign-ups in the last quarter"
"What are the most popular features used by premium users?"
"How has user retention changed month-over-month?"
```

### Product Performance

```
"What are the top events by volume this week?"
"Show me user engagement trends for the last 30 days"
"Compare conversion rates across different traffic sources"
```

### Data Discovery

```
"What events and properties are available in the mobile app schema?"
"Show me all custom properties for the checkout event"
"What dimensions can I use for user segmentation?"
```

---

## Typical Workflow

Here's how most analysis sessions flow:

```
Initialize → Explore → Search → Create → Export
```

1. **Initialize** - Call `getUserContext` to see available schemas
2. **Explore** - Use `getSchema` to understand events and properties  
3. **Search** - Check `searchKubit` for existing analyses
4. **Create** - Generate new reports with custom queries
5. **Export** - Pull `getRawData` for external analysis

---

## Best Practices

### Crafting Effective Prompts

**Be Specific**  
Include time ranges, events, and segments in your questions.

```diff
- "Show me users"
+ "Show me active users in the US who signed up last month"
```

**Provide Context**  
Explain what you're trying to understand.

```diff
- "What's the conversion rate?"
+ "What's the conversion rate from free trial to paid for users who engaged with feature X?"
```

**Reference Schemas**  
Use schema names when working with multiple data sources.

```diff
- "Show me sign-up events"
+ "In the mobile_events schema, show me sign-up events"
```

**Break It Down**  
Complex analyses work better as multiple focused questions.

```diff
- "Show me everything about user behavior across all channels with retention and conversion"
+ Start with "Show me user retention by channel" then follow up
```

### Performance Optimization

- **Use `searchKubit` first** - Leverage existing analyses before creating new reports
- **Specify date ranges** - Narrow time windows improve query performance  
- **Export selectively** - Only use `getRawData` when you need detailed external analysis

### Security & Compliance

| Consideration | What It Means |
|---------------|---------------|
| **Permission Model** | You can only access schemas you're authorized to view |
| **AI Processing** | Third-party AI models will process your query data |
| **Policy Review** | Confirm your organization allows AI-assisted data analysis |

---

## Troubleshooting

### Common Issues & Solutions

**Authentication Failures**  
Verify your Kubit credentials and organization name

**No Schemas Available**  
Check that you have access to at least one schema in Kubit

**Connection Errors**  
Confirm you're using the correct server URL: `https://mcp.kubit.ai/mcp`

**Report Generation Issues**  
Verify the schema and events you're referencing exist using `getSchema`

### Need Help?

- Test with simple queries first to verify your connection
- Check schema access through the Kubit web interface  
- Use `getSchema` to confirm available events and properties

---

## Support & Resources

**Documentation**  
[docs.kubit.ai](https://docs.kubit.ai/) - Complete platform documentation

**Customer Success**  
Contact your Kubit customer success team for assistance

**About Kubit**  
[kubit.ai](https://kubit.ai) - Learn more about warehouse-native analytics

**MCP Protocol**  
[modelcontextprotocol.io](https://modelcontextprotocol.io) - Explore the Model Context Protocol