> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zyeta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Understanding Model Context Protocol (MCP) integration, intelligent server recommendations, and multi-tool orchestration

The MCP (Model Context Protocol) Integration in Definable.ai enables AI agents to connect to external services and tools through a standardized protocol. It provides intelligent server recommendations, multi-tool orchestration, and seamless OAuth-based authentication for accessing third-party platforms like Gmail, Slack, GitHub, and hundreds of other services.

## What is MCP?

**Model Context Protocol (MCP)** is an open standard that enables Large Language Models to securely connect to external data sources and tools. Think of it as a universal adapter that lets AI agents interact with any service that implements the protocol.

**Key Benefits:**

* **Universal Standard**: One protocol to connect to hundreds of services
* **Secure**: OAuth-based authentication with proper access controls
* **Contextual**: AI agents can access real-time data from connected services
* **Extensible**: Easy to add new MCP servers and tools
* **Intelligent**: AI automatically discovers and uses relevant tools

## MCP System Architecture

```mermaid theme={null}
graph TB
    subgraph "User Interface"
        User[👤 User]
        Chat[💬 Chat Interface]
    end

    subgraph "Definable.ai Platform"
        PlaygroundService[🎮 MCP Playground Service]
        MCPService[🔧 MCP Service]
        IntelligentAgent[🧠 Intelligent Agent]
        Database[(📊 Database)]
    end

    subgraph "MCP Layer"
        MCPFactory[🏭 MCP Factory]
        MultiMCPTools[🛠️ Multi-MCP Tools]
    end

    subgraph "Authentication"
        Composio[🔐 Composio API]
        OAuth[🔑 OAuth Flow]
    end

    subgraph "External MCP Servers"
        Gmail[📧 Gmail MCP]
        Slack[💬 Slack MCP]
        GitHub[🐙 GitHub MCP]
        Other[... 100+ More]
    end

    User --> Chat
    Chat --> PlaygroundService

    PlaygroundService --> IntelligentAgent
    PlaygroundService --> MCPFactory

    IntelligentAgent --> Database
    IntelligentAgent -.Recommends.-> MCPService

    MCPFactory --> MultiMCPTools
    MCPService --> Composio
    MCPService --> Database

    Composio --> OAuth
    OAuth --> Gmail
    OAuth --> Slack
    OAuth --> GitHub

    MultiMCPTools --> Gmail
    MultiMCPTools --> Slack
    MultiMCPTools --> GitHub
    MultiMCPTools --> Other

    style PlaygroundService fill:#e3f2fd
    style IntelligentAgent fill:#f3e5f5
    style MCPFactory fill:#e8f5e8
    style Composio fill:#fff3e0
```

## Core Components

### 1. MCP Servers

MCP Servers are external services that implement the Model Context Protocol.

**Properties:**

* **Toolkit Name**: Human-readable name (e.g., "Gmail", "Slack")
* **Toolkit Slug**: URL-safe identifier (e.g., "gmail", "slack")
* **Auth Scheme**: Authentication method (OAuth2, API Key, etc.)
* **Tools**: Collection of functions the server provides
* **Logo**: Visual identifier for the service

**Example MCP Servers:**

* **Gmail MCP Server**: List Emails, Send Email, Search Emails, Read Email, Delete Email
* **Slack MCP Server**: Send Message, List Channels, Create Channel, Upload File
* **GitHub MCP Server**: Create Issue, List Repos, Create PR, Comment on Issue
* **Notion MCP Server**: Create Page, Update Database, Search Content

### 2. MCP Tools

Individual functions provided by MCP servers.

**Tool Structure:**

* **Name**: Function name (e.g., "send\_email")
* **Slug**: Unique identifier (e.g., "gmail\_send\_email")
* **Description**: What the tool does
* **Parameters**: Input schema for the tool
* **Server**: Parent MCP server

### 3. MCP Sessions (Instances)

User connections to MCP servers.

**Session Lifecycle:**

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending: Connect Account
    Pending --> Active: OAuth Success
    Pending --> [*]: OAuth Failed
    Active --> Active: Use Tools
    Active --> [*]: Disconnect

    state Pending {
        [*] --> CreateSession
        CreateSession --> OAuthRedirect
        OAuthRedirect --> WaitingCallback
    }

    state Active {
        [*] --> Connected
        Connected --> GenerateURL
        GenerateURL --> UseMCPTools
    }
```

**Session Properties:**

* **Instance ID**: Unique identifier for this connection
* **Server ID**: Which MCP server is connected
* **User ID**: Who owns this connection
* **Organization ID**: Which org this belongs to
* **Status**: pending, active, inactive
* **Name**: Custom name for the instance
* **Connected Account ID**: Composio account reference

### 4. Intelligent Agent

AI that analyzes queries and recommends MCP servers.

**How It Works:**

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Agent
    participant Database
    participant MCPPlayground

    User->>Agent: "Send an email to john@example.com"
    Agent->>Database: Query mcp_servers and mcp_tools
    Database-->>Agent: Find Gmail server
    Agent->>Agent: Analyze intent
    Agent-->>User: "I'll help you send an email"
    Agent-->>MCPPlayground: Recommend Gmail server
    MCPPlayground->>User: Prompt to connect Gmail
```

**Agent Capabilities:**

* Analyzes user intent from natural language
* Searches database for relevant MCP servers
* Understands tool descriptions and capabilities
* Maintains conversation context
* Returns server recommendations in structured format

### 5. MCP Playground Factory

Orchestrates conversations with multiple MCP servers.

**Features:**

* **Multi-Server Support**: Connect to multiple MCPs simultaneously
* **Conversation Memory**: Maintains 30-message history (configurable)
* **Tool Metadata**: Tracks pagination tokens and result counts
* **Structured Prompting**: Better context for AI responses
* **Model Flexibility**: Supports OpenAI, Anthropic, DeepSeek, Gemini

## MCP Modes

### Mode 1: Intelligent Discovery

User chats naturally, AI discovers and recommends MCP servers.

**Flow:**

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Playground
    participant IntelligentAgent
    participant DB

    User->>Playground: "What emails did I get today?"
    Playground->>IntelligentAgent: Analyze query (no mcp_instance_ids)
    IntelligentAgent->>DB: Search for email-related MCP servers
    DB-->>IntelligentAgent: Gmail MCP server found
    IntelligentAgent-->>User: Stream: "To check your emails, I need access to Gmail"
    IntelligentAgent-->>User: Stream: Recommend Gmail server
    User->>User: Frontend prompts to connect Gmail
    User->>User: Completes OAuth
    User->>Playground: "What emails did I get today?" (with mcp_instance_ids)
    Playground->>Gmail: List emails via MCP
    Gmail-->>Playground: Email list
    Playground-->>User: "You have 5 new emails: ..."
```

**Benefits:**

* No manual server selection needed
* Natural language interaction
* AI suggests relevant tools
* Seamless connection flow

### Mode 2: Direct MCP Usage

User explicitly provides MCP instance IDs to use.

**Flow:**

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Playground
    participant MCPFactory
    participant Gmail
    participant Slack

    User->>Playground: "Forward my urgent emails to Slack"
    Note over User,Playground: mcp_instance_ids: [gmail-id, slack-id]

    Playground->>MCPFactory: Initialize with [Gmail, Slack] URLs
    MCPFactory->>Gmail: Connect
    MCPFactory->>Slack: Connect

    MCPFactory->>Gmail: Search emails (urgent)
    Gmail-->>MCPFactory: Tool Start Event
    MCPFactory-->>User: Stream: Searching emails...
    Gmail-->>MCPFactory: Tool Complete Event
    MCPFactory-->>User: Stream: Found 5 urgent emails

    MCPFactory->>Slack: Send message
    Slack-->>MCPFactory: Tool Start Event
    MCPFactory-->>User: Stream: Sending to Slack...
    Slack-->>MCPFactory: Tool Complete Event
    MCPFactory-->>User: Stream: "Forwarded 3 urgent emails to #general"

    MCPFactory-->>User: Stream: DONE
```

**Benefits:**

* Full control over which servers to use
* Faster execution (no discovery phase)
* Multi-server orchestration
* Complex workflows

## Authentication Flow

### OAuth Connection Process

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Frontend
    participant MCPService
    participant Composio
    participant ExternalService

    User->>Frontend: Connect Gmail
    Frontend->>MCPService: POST /mcp/connect_account
    MCPService->>Composio: Create connected account
    Composio->>Composio: Generate auth URL
    Composio-->>MCPService: redirect_url, connected_account_id
    MCPService->>DB: Store session (status=pending)
    MCPService-->>Frontend: redirect_url

    Frontend->>User: Redirect to OAuth page
    User->>ExternalService: Grant permissions
    ExternalService->>Composio: OAuth callback
    Composio->>MCPService: GET /mcp/callback

    MCPService->>MCPService: Update session (status=active)
    MCPService->>Composio: Create MCP instance
    Composio-->>MCPService: Instance created
    MCPService-->>Frontend: Redirect with success
    Frontend->>User: "Gmail connected!"
```

**Key Steps:**

1. **Initiate**: User clicks "Connect" on MCP server
2. **Prepare**: System creates pending session record
3. **Redirect**: User redirected to OAuth provider
4. **Authorize**: User grants permissions
5. **Callback**: OAuth provider redirects back
6. **Activate**: Session marked as active
7. **Instance**: MCP instance auto-created
8. **Ready**: User can now use MCP tools

## Tool Execution

### Tool Call Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> ToolCallStarted: AI decides to use tool
    ToolCallStarted --> Processing: Execute tool
    Processing --> ToolCallCompleted: Success
    Processing --> ToolCallCompleted: Error
    ToolCallCompleted --> [*]

    state ToolCallStarted {
        [*] --> SendStartEvent
        SendStartEvent --> ShowToolInfo
        ShowToolInfo --> [*]
    }

    state Processing {
        [*] --> CallMCPServer
        CallMCPServer --> WaitResponse
        WaitResponse --> ParseResult
        ParseResult --> ExtractMetadata
        ExtractMetadata --> [*]
    }

    state ToolCallCompleted {
        [*] --> SendCompleteEvent
        SendCompleteEvent --> ShowResult
        ShowResult --> StreamToUser
        StreamToUser --> [*]
    }
```

**Event Types:**

**1. Tool Call Started** - AI initiates a tool call with input parameters

**2. Tool Call Completed** - Tool execution finished with results including success status, output data, and optional pagination metadata

### Pagination Support

MCP tools that return large datasets support pagination.

**Metadata Tracking:**

* `nextPageToken`: Token for next page of results
* `resultSizeEstimate`: Total number of results available

The system automatically stores this metadata and uses it when users request "more" results.

## Conversation Management

### Memory System

**Conversation Storage:**

* **Format**: Array of role, content, created\_at
* **Intelligent Mode Limit**: Last 30 exchanges (60 messages max)
* **Direct Mode Limit**: Last 30 messages (configurable via memory\_size parameter)
* **TTL**: 30 minutes of inactivity
* **Structure**: Chronological order

**Mode-Specific Behavior:**

* **Intelligent Discovery Mode**: Uses last 30 conversation exchanges for context
* **Direct MCP Mode**: Passes memory\_size=30 to playground factory (adjustable)

**History Usage:**

The system automatically includes conversation history in each request enabling contextual interactions like:

* "Show me more" - AI remembers previous query
* "Send that to Slack" - AI knows what "that" refers to
* "What was the first email about?" - AI recalls earlier context

### Structured Prompting

The MCP Playground uses structured prompts for better context management.

**Prompt Components:**

* **System Instructions**: Agent identity, capabilities, tool usage principles
* **Current Message**: User's current query with timestamp
* **Conversation History**: Previous exchanges in chronological order
* **Tool Guidelines**: How to analyze tool structure and use parameters correctly

**Benefits:**

* **Better Context**: Clear separation of roles and information
* **Improved Parsing**: LLMs understand structured formats well
* **Explicit Instructions**: Detailed guidelines for tool usage
* **History Awareness**: Full conversation context included

## Supported Models

The MCP Playground supports multiple LLM providers with hardcoded defaults for each mode:

| Provider      | Supported Models | Mode Default                         | Best For                         |
| ------------- | ---------------- | ------------------------------------ | -------------------------------- |
| **OpenAI**    | gpt-*, o1*       | -                                    | General purpose, reasoning       |
| **Anthropic** | claude-\*        | -                                    | Tool use, long context           |
| **DeepSeek**  | deepseek-\*      | **Intelligent Mode** (deepseek-chat) | Cost-effective, database queries |
| **Google**    | gemini-\*        | **Direct Mode** (gemini-2.5-flash)   | Fast tool execution              |

**Default Behavior:**

* **Intelligent Discovery Mode**: Uses `deepseek-chat` if no model specified
* **Direct MCP Mode**: Uses `gemini-2.5-flash` if no model specified
* Users can override by specifying any supported model in the request

## Use Cases

### Email Management

**Scenario**: Manage Gmail inbox with natural language

**Example Workflow:**

1. User: "Show me urgent emails from last week"
2. AI calls gmail\_search\_messages with appropriate query
3. AI: "You have 8 urgent emails from last week..."
4. User: "Forward the one from Sarah to my team Slack"
5. AI calls gmail\_get\_message and slack\_send\_message
6. AI: "Forwarded Sarah's email to #team-updates"

**MCP Servers Used**: Gmail, Slack

### Project Management

**Scenario**: Sync GitHub issues with project management tools

**Example Workflow:**

1. User: "What issues are open in our main repo?"
2. AI calls github\_list\_issues
3. AI: "You have 24 open issues. 5 are labeled as bugs..."
4. User: "Create a Notion page for the critical bugs"
5. AI calls github\_list\_issues (filter:critical+bug) and notion\_create\_page
6. AI: "Created Notion page with 5 critical bugs"

**MCP Servers Used**: GitHub, Notion, Slack

### Data Analysis

**Scenario**: Analyze data from multiple sources

**Example Workflow:**

1. User: "Show me this week's sales from Stripe"
2. AI calls stripe\_list\_charges
3. AI: "This week you processed \$45,230 in 156 transactions"
4. User: "Export to Google Sheets"
5. AI calls google\_sheets\_append\_rows
6. AI: "Added to 'Weekly Sales' sheet"

**MCP Servers Used**: Stripe, Google Sheets, Slack

### Customer Support

**Scenario**: Access customer data across platforms

**Example Workflow:**

1. User: "Find customer info for [john@example.com](mailto:john@example.com)"
2. AI calls hubspot\_search\_contacts and stripe\_search\_customers
3. AI: "Found John Smith - Enterprise plan, joined Jan 2024..."
4. User: "What tickets does he have?"
5. AI calls zendesk\_search\_tickets
6. AI: "3 open tickets, 2 are about billing..."

**MCP Servers Used**: HubSpot, Stripe, Zendesk, Gmail

## Best Practices

### For Users

1. **Connect Relevant Servers**: Only connect MCP servers you'll actually use
2. **Use Natural Language**: Let the AI discover appropriate tools
3. **Provide Context**: Reference previous conversations for continuity
4. **Be Specific**: Clear requests get better results
5. **Review Permissions**: Understand what access you're granting

### For Developers

1. **Server Selection**: Choose MCP servers that match your use case
2. **Error Handling**: Handle OAuth failures and tool errors gracefully
3. **Pagination**: Implement pagination for large result sets
4. **Rate Limiting**: Respect MCP server rate limits
5. **Security**: Never store or log sensitive OAuth tokens

### Tool Usage Guidelines

1. **Comprehensive Searches**: Don't limit to single criteria
   * Bad: Search only "urgent" emails
   * Good: Search "urgent OR important OR high-priority OR from:boss"

2. **Efficient Calls**: Break large operations into smaller calls
   * Bad: Process 1000 items in one call
   * Good: Process in batches of 50-100

3. **Metadata Usage**: Leverage pagination metadata
   * Check `nextPageToken` for more results
   * Use `resultSizeEstimate` to inform user

4. **Parameter Analysis**: Understand all tool parameters
   * Read tool descriptions carefully
   * Use only relevant parameters
   * Validate input before calling

## Security Considerations

### OAuth Security

* **Scopes**: Only request necessary permissions
* **Token Storage**: Tokens managed by Composio, never stored locally
* **Expiration**: Tokens automatically refreshed
* **Revocation**: Users can disconnect anytime

### Data Privacy

* **No Storage**: MCP responses not permanently stored
* **Session Privacy**: Conversations cleared after TTL
* **Org Isolation**: MCP sessions scoped to organizations
* **User Isolation**: Users only see their own connections

### Access Control

* **RBAC**: Requires `mcp:write` and `mcp:read` permissions
* **Feature Flags**: `mcp_sessions` quota enforcement
* **Org Scoping**: All operations org-scoped
* **User Verification**: JWT authentication required

## Performance Optimization

### Connection Management

* **Connection Reuse**: MCP connections maintained during chat
* **Cleanup**: Automatic connection closure after response
* **Timeout**: 30-second timeout for MCP operations
* **Parallel Tools**: Multiple MCP servers used simultaneously

### Memory Management

* **Intelligent Mode History**: 60 messages max (30 exchanges)
* **Direct Mode History**: 30 messages (configurable via memory\_size)
* **TTL Cleanup**: Inactive sessions cleared after 30 minutes
* **Metadata Pruning**: Tool metadata cleared after use
* **Auto Cleanup**: Old messages automatically trimmed when limit reached

### Streaming Optimization

* **Chunk Size**: 10-token chunks for smooth streaming
* **Event Filtering**: Only stream relevant events
* **Tool Events**: Separate tool call events from content
* **Buffer Management**: Clear buffers after sending

## Troubleshooting

### Connection Issues

**Problem**: OAuth fails or times out

**Solutions:**

* Check internet connectivity
* Verify MCP server is operational
* Try different browser (clear cache)
* Check Composio service status

### Tool Call Failures

**Problem**: Tool returns error or times out

**Solutions:**

* Verify permissions were granted
* Check tool parameters are correct
* Ensure data exists (e.g., email to fetch)
* Review MCP server documentation

### Session Problems

**Problem**: Session shows as "pending" forever

**Solutions:**

* Check OAuth callback URL is correct
* Verify no firewall blocking callback
* Try disconnecting and reconnecting
* Check Composio logs for errors

### Performance Issues

**Problem**: Slow responses or timeouts

**Solutions:**

* Reduce number of simultaneous MCP servers
* Limit history size (use smaller memory\_size)
* Break large operations into smaller chunks
* Check MCP server latency

## Limitations

### Current Limitations

* **Model Support**: Limited to 4 providers (OpenAI, Anthropic, DeepSeek, Gemini)
* **Timeout**: 30-second max for MCP operations
* **History Limits**:
  * Intelligent Mode: 60 messages (30 exchanges)
  * Direct Mode: 30 messages default (configurable)
* **Concurrent MCPs**: Performance degrades with too many servers
* **OAuth Only**: Limited to OAuth-based authentication

### Future Enhancements

* API key authentication support
* Longer conversation history
* MCP server caching
* Custom MCP server creation
* Advanced tool composition
* Workflow automation

## Next Steps

Explore MCP integration in depth:

* [**MCP Service API**](/pages/api-reference/mcp-service) - Manage MCP servers and connections
* [**MCP Playground API**](/pages/api-reference/mcp-playground-service) - Chat with MCP tools
* [**Agents**](/pages/concepts/agents) - Build AI agents with MCP tools
* [**Authentication**](/pages/authentication/overview) - Security and access control

Ready to connect your first MCP server? Check out the [**Quick Start Guide**](/pages/getting-started/quickstart) or explore our [**API Reference**](/pages/api-reference/mcp-service).