# MCP Hubby - Complete Documentation

> MCP Hubby is a Model Context Protocol gateway that connects AI assistants like Claude to your tools through OAuth. One configuration, works everywhere.

## Table of Contents

1. [Quick Start](#quick-start)
2. [What is MCP Hubby](#what-is-mcp-hubby)
3. [Key Features](#key-features)
4. [Available Integrations](#available-integrations)
5. [How It Works](#how-it-works)
6. [Setup Guides](#setup-guides)
7. [Integration Details](#integration-details)
8. [Technical Architecture](#technical-architecture)
9. [API Reference](#api-reference)
10. [Troubleshooting](#troubleshooting)

## Quick Start

1. Visit https://mcphubby.ai
2. Sign in with your email
3. Connect your first service (Gmail, Notion, etc.) with one click
4. Copy the MCP configuration from your hub
5. Add to Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac)
6. Restart Claude Desktop
7. Test by asking Claude to access your connected service

## What is MCP Hubby?

MCP Hubby is a cloud-hosted gateway for the Model Context Protocol (MCP). It eliminates the complexity of managing multiple MCP server configurations, API keys, and local servers.

### The Problem We Solve

**Without MCP Hubby:**
- Hunt for API keys across 15+ services
- Manage separate MCP server configs for each service
- Run local servers that consume RAM and crash
- Different setup for each AI tool (Claude, Cursor, VS Code)
- Huge context window overhead loading all tools upfront
- Tool name collisions between services

**With MCP Hubby:**
- One-click OAuth connection for all services
- Single gateway configuration
- Cloud-hosted, always reliable
- Same config works everywhere
- 90% context reduction with progressive loading
- Namespaced tools prevent collisions

## Key Features

### One-Click OAuth
Connect services through standard OAuth flows. No need to generate API keys, manage credentials, or store sensitive tokens locally.

### Progressive Loading
Instead of loading 200+ tool definitions upfront, our gateway shows Claude what's available, then loads full capabilities only when needed. This achieves 90% reduction in context usage.

### Universal Configuration
Copy your MCP config once, use it in Claude Desktop, Cursor, VS Code, or any MCP client. Update connections in our dashboard without touching config files.

### Cloud-Hosted Gateway
No local servers to manage, crash, or consume resources. Our infrastructure handles all the complexity.

### Namespaced Tools
Each service gets its own namespace (gmail, notion, etc.) preventing tool name collisions. Example: `gmail(action='search')` vs `notion(action='search')`.

## Available Integrations

### Gmail
**Authentication**: OAuth
**Operations**: search, send, draft, read, list_labels, create_label, modify_labels, raw_api
**Use Cases**: Email management, automated responses, search across threads
**Documentation**: https://developers.google.com/gmail/api

### Google Calendar
**Authentication**: OAuth
**Operations**: list_events, create_event, update_event, delete_event, list_calendars, raw_api
**Use Cases**: Schedule management, meeting creation, availability checking
**Documentation**: https://developers.google.com/calendar

### Notion
**Authentication**: OAuth
**Operations**: search, list_databases, query_database, create_page, update_page, get_page, append_blocks, create_database, raw_api
**Use Cases**: Knowledge management, project tracking, documentation
**Documentation**: https://developers.notion.com

### Slack
**Authentication**: OAuth
**Status**: In Testing
**Operations**: send_message, list_channels, get_channel_history, raw_api
**Use Cases**: Team communication, notifications, channel management
**Documentation**: https://api.slack.com

### ClickUp
**Authentication**: OAuth
**Operations**: get_authorized_teams, get_spaces, get_lists, get_tasks, get_task, create_task, update_task, delete_task, add_comment, get_comments, get_time_entries, raw_api
**Use Cases**: Task management, project tracking, team collaboration
**Documentation**: https://clickup.com/api

### Dropbox
**Authentication**: OAuth
**Operations**: list_folder, download_file, upload_file, create_folder, delete, move, search, get_metadata, raw_api
**Use Cases**: File storage, sharing, backup
**Documentation**: https://www.dropbox.com/developers/documentation

### Limitless
**Authentication**: API Key
**Operations**: search, get_transcript, list_recent
**Use Cases**: AI wearable notes, meeting transcripts, memory search
**Documentation**: https://my.limitless.ai/settings/api-keys

### Fireflies.ai
**Authentication**: API Key
**Status**: In Testing
**Operations**: search_transcripts, get_transcript
**Use Cases**: Meeting summaries, transcript search
**Documentation**: https://app.fireflies.ai/integrations/custom/fireflies

## How It Works

### Architecture Overview

```
Your AI (Claude/Cursor)
  ↓ MCP Protocol
MCP Hubby Gateway (Cloud)
  ↓ OAuth/API Calls
Your Connected Services (Gmail/Notion/etc)
```

### Connection Flow

1. **User Authentication**: Sign in to MCP Hubby dashboard
2. **Service Connection**: Click "Connect" → OAuth flow → Credentials stored encrypted
3. **Config Generation**: MCP Hubby generates your unique gateway URL with token
4. **AI Configuration**: Add config to your AI tool
5. **Tool Discovery**: AI calls `tools/list` → Gateway returns available tools
6. **Progressive Loading**: AI calls `describe` action → Gateway returns full operation details
7. **Tool Execution**: AI calls specific operation → Gateway routes to service adapter → Returns response

### Gateway Pattern

Each connected service exposes ONE tool with an `action` parameter:

```json
{
  "name": "gmail",
  "description": "Access your Gmail. Available operations: search, send, draft, read...",
  "inputSchema": {
    "properties": {
      "action": { "type": "string", "description": "Operation to perform" },
      "params": { "type": "object", "description": "Operation parameters" }
    }
  }
}
```

This reduces context by 95% vs exposing all operations upfront.

## Setup Guides

### Claude Desktop Setup

1. **Connect Services**:
   - Visit https://mcphubby.ai/hub
   - Click "Connect" on services you want to use
   - Complete OAuth flows

2. **Get MCP Config**:
   - Click "Connect To AI" button
   - Copy the configuration shown

3. **Add to Claude Desktop**:
   - Open config file:
     - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
     - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Add MCP Hubby config to the `mcpServers` section
   - Save file

4. **Restart Claude Desktop**

5. **Test**:
   - Ask Claude: "What services are available?"
   - Ask Claude to use a connected service

### Cursor Setup

1. **Connect Services** (same as Claude Desktop)
2. **Get MCP Config** (same as Claude Desktop)
3. **Add to Cursor**:
   - Open Cursor settings
   - Navigate to MCP section
   - Add MCP Hubby configuration
4. **Restart Cursor**
5. **Test** with connected services

### VS Code Setup

1. **Connect Services** (same as above)
2. **Get MCP Config**
3. **Add to VS Code**:
   - Install Cline extension
   - Open Cline MCP settings
   - Add MCP Hubby configuration
4. **Reload VS Code**
5. **Test** with connected services

## Integration Details

### Gmail Operations

**search**: Find emails by query
```
Parameters:
- query (string, required): Gmail search query (e.g., "from:john subject:meeting")
- maxResults (number, optional): Max results to return (default: 10)
```

**send**: Send an email
```
Parameters:
- to (string, required): Recipient email
- subject (string, required): Email subject
- body (string, required): Email body (HTML or plain text)
- cc (string, optional): CC recipients
- bcc (string, optional): BCC recipients
```

**draft**: Create a draft
```
Parameters: Same as send
```

**read**: Read an email by ID
```
Parameters:
- messageId (string, required): Gmail message ID
```

### Notion Operations

**search**: Search across workspace
```
Parameters:
- query (string, required): Search query
```

**query_database**: Query a database
```
Parameters:
- database_id (string, required): Database ID
- filter (object, optional): Query filter
- sorts (array, optional): Sort configuration
```

**create_page**: Create a new page
```
Parameters:
- parent (object, required): Parent page or database
- properties (object, required): Page properties
- children (array, optional): Page content blocks
```

### ClickUp Operations

**get_tasks**: Get tasks with filters
```
Parameters:
- list_id (string, optional): List ID
- team_id (string, optional): Team ID
- statuses (array, optional): Filter by status
- assignees (array, optional): Filter by assignee
- due_date_gt (number, optional): Due after timestamp
- include_closed (boolean, optional): Include closed tasks
```

**create_task**: Create a new task
```
Parameters:
- list_id (string, required): List ID
- name (string, required): Task name
- description (string, optional): Task description
- assignees (array, optional): User IDs to assign
- status (string, optional): Status name
- priority (number, optional): 1=urgent, 2=high, 3=normal, 4=low
- due_date (number, optional): Unix timestamp
- tags (array, optional): Tag names
```

## Technical Architecture

### Authentication

**Token-Based**: Each user gets a unique MCP token embedded in their gateway URL.

**OAuth Flow**:
1. User clicks "Connect" in dashboard
2. Redirect to service OAuth page
3. User authorizes MCP Hubby
4. Service returns OAuth credentials
5. Credentials encrypted and stored
6. Connection marked as CONNECTED

**API Key Services** (Limitless, Fireflies):
User provides API key → Encrypted and stored → Used for all requests

### Security

- Credentials encrypted at rest (AES-256)
- Credentials encrypted in transit (TLS)
- MCP tokens are unique per user
- Tokens can be revoked anytime
- No credential sharing between users
- SOC2 Type II compliant infrastructure

### Data Storage

**Database**: PostgreSQL with Prisma ORM

**Models**:
- User: Email, Clerk ID, timestamps
- Connection: Service, credentials, status
- Token: MCP auth tokens
- ActivityLog: Request logs for analytics

### Rate Limiting

**Per User**:
- Free: 20k requests/month
- Pro: 200k requests/month
- Team: 1M requests/month

**Per Service**: Respects each service's rate limits

### Error Handling

All errors return MCP-compliant error responses:

```json
{
  "content": [{
    "type": "text",
    "text": "Error message with actionable information"
  }],
  "isError": true
}
```

## API Reference

### MCP Endpoints

**Initialize**: `POST /mcp/{token}`
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": 1
}
```

**List Tools**: `POST /mcp/{token}`
```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}
```

**Call Tool**: `POST /mcp/{token}`
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "gmail",
    "arguments": {
      "action": "search",
      "params": {
        "query": "from:john"
      }
    }
  },
  "id": 3
}
```

### REST API (Dashboard)

**Get Connections**: `GET /api/connections`
**Create Token**: `POST /api/tokens`
**Revoke Token**: `DELETE /api/tokens/{id}`

## Troubleshooting

### Connection Issues

**Service shows as "Expired"**:
- Reconnect the service in dashboard
- OAuth tokens expire after 30-90 days depending on service

**Service shows as "Error"**:
- Check error message in dashboard
- Try disconnecting and reconnecting
- Verify service is operational

### Claude Desktop Issues

**Claude doesn't see MCP Hubby**:
- Verify config JSON is valid (use JSONLint)
- Restart Claude Desktop completely
- Check Developer Tools console for errors

**Tools not showing**:
- Ask Claude: "What services are available?"
- Use `mcp_hubby_list_services` tool explicitly
- Verify connections in dashboard are "CONNECTED"

### Performance Issues

**Slow responses**:
- Check service status (some services have rate limits)
- Verify network connectivity
- Check analytics dashboard for high error rates

**High error rates**:
- Review activity log for specific errors
- Check if service credentials expired
- Verify service API is operational

### Common Errors

**"Service not connected"**:
- Connect the service in dashboard
- Refresh AI client

**"Invalid token"**:
- Regenerate MCP token in dashboard
- Update AI client config
- Restart AI client

**"Rate limit exceeded"**:
- Wait for rate limit window to reset
- Upgrade to higher tier if needed
- Distribute requests over time

## Support

**Documentation**: https://mcphubby.ai/docs
**Dashboard**: https://mcphubby.ai/hub
**Status**: Check service status in dashboard
**Contact**: support@mcphubby.ai

## Links

- Website: https://mcphubby.ai
- Dashboard: https://mcphubby.ai/hub
- Integrations: https://mcphubby.ai/integrations
- Analytics: https://mcphubby.ai/hub/analytics
- Setup Guide: https://mcphubby.ai/docs/setup/claude-desktop