> ## 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 Playground Service API

> API reference for chatting with MCP servers, intelligent server recommendations, and multi-tool orchestration

The MCP Playground Service provides a conversational interface for interacting with MCP servers. It supports two modes: **Intelligent Discovery** (AI recommends servers) and **Direct MCP Usage** (use specific servers). The service handles tool orchestration, streaming responses, and conversation management.

## MCP Playground Overview

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

    alt Intelligent Discovery Mode
        User->>Playground: "Show my urgent emails"
        Note over Playground: No mcp_instance_ids provided
        Playground->>IntelligentAgent: Analyze query
        IntelligentAgent->>Database: Search MCP servers
        IntelligentAgent-->>User: {"mcp": {"server_ids": ["gmail"]}}
        User->>User: Connect Gmail via OAuth
    end

    alt Direct MCP Mode
        User->>Playground: "Show my urgent emails"
        Note over Playground: mcp_instance_ids: [gmail-id]
        Playground->>MCPFactory: Initialize with Gmail URL
        MCPFactory->>Gmail: Connect & List messages
        Gmail-->>MCPFactory: Tool Start Event
        MCPFactory-->>User: Stream: Searching emails...
        Gmail-->>MCPFactory: Tool Complete Event
        MCPFactory-->>User: Stream: Found 5 urgent emails
        MCPFactory-->>User: Stream: Email details...
        MCPFactory-->>User: Stream: DONE
    end
```

## Authentication

Requires a valid Bearer token with `mcp:write` permission.

## Base URL

```
/api/mcp_playground
```

## Chat with MCP

### Send Message to MCP Playground

Send a message and receive streaming responses from AI using MCP tools.

<CodeGroup>
  ```bash curl theme={null}
  # Intelligent Discovery Mode (no MCP instances)
  curl -X POST "{{baseUrl}}/api/mcp_playground/chat" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "Show me my urgent emails from today",
      "model": "gpt-4-turbo"
    }'

  # Direct MCP Mode (with specific instances)
  curl -X POST "{{baseUrl}}/api/mcp_playground/chat" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "Forward urgent emails to Slack",
      "mcp_instance_ids": ["gmail-instance-id", "slack-instance-id"],
      "model": "claude-3.5-sonnet"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "{{baseUrl}}/api/mcp_playground/chat"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  # Intelligent Discovery Mode
  data_discovery = {
      "content": "Show me my urgent emails from today",
      "model": "gpt-4-turbo"
  }

  # Direct MCP Mode
  data_direct = {
      "content": "Forward urgent emails to Slack",
      "mcp_instance_ids": ["gmail-instance-id", "slack-instance-id"],
      "model": "claude-3.5-sonnet"
  }

  # Send request with streaming
  response = requests.post(url, headers=headers, json=data_direct, stream=True)

  # Process streaming response
  for line in response.iter_lines():
      if line:
          decoded = line.decode('utf-8')
          if decoded.startswith('data: '):
              import json
              data = json.loads(decoded[6:])

              if data.get('message') == 'DONE':
                  print('\n--- Stream Complete ---')
                  break

              if data.get('error'):
                  print(f'Error: {data["error"]}')
                  break

              # Tool call events
              if data.get('tool'):
                  tool = data['tool']
                  if tool['output'] is None:
                      print(f"[Tool Start] {tool['name']}: {tool['input']}")
                  else:
                      status = "✓" if tool.get('successful') else "✗"
                      print(f"[Tool Complete {status}] {tool['name']}")

              # Regular message content
              if data.get('message'):
                  print(data['message'], end='', flush=True)
  ```

  ```typescript TypeScript theme={null}
  interface MCPPlaygroundMessage {
    content: string;
    mcp_instance_ids?: string[];
    model?: string;
  }

  interface ToolEvent {
    id: string;
    name: string;
    input?: Record<string, any>;
    output?: any;
    successful?: boolean;
    error?: string | null;
  }

  interface StreamData {
    message: string;
    tool: ToolEvent | null;
    error?: string;
    mcp?: {
      server_ids: string[];
    };
  }

  const chatWithMCP = async (
    message: MCPPlaygroundMessage,
    onToken: (token: string) => void,
    onTool: (tool: ToolEvent) => void,
    onMCPRecommendation: (serverIds: string[]) => void
  ) => {
    const response = await fetch('{{baseUrl}}/api/mcp_playground/chat', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(message),
    });

    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { value, done } = await reader!.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n');

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data: StreamData = JSON.parse(line.slice(6));

          if (data.message === 'DONE') {
            console.log('Stream complete');
            return;
          }

          if (data.error) {
            throw new Error(data.error);
          }

          // MCP server recommendations (Intelligent Mode)
          if (data.mcp?.server_ids) {
            onMCPRecommendation(data.mcp.server_ids);
          }

          // Tool events
          if (data.tool) {
            onTool(data.tool);
          }

          // Regular content
          if (data.message && data.message !== 'DONE') {
            onToken(data.message);
          }
        }
      }
    }
  };

  // Usage - Intelligent Discovery
  await chatWithMCP(
    {
      content: "Show me my urgent emails",
      model: "gpt-4-turbo"
    },
    (token) => console.log(token),
    (tool) => console.log('Tool:', tool.name),
    (serverIds) => {
      console.log('Recommended servers:', serverIds);
      // Prompt user to connect these servers
    }
  );

  // Usage - Direct MCP
  await chatWithMCP(
    {
      content: "Forward urgent emails to Slack",
      mcp_instance_ids: ["gmail-id", "slack-id"],
      model: "claude-3.5-sonnet"
    },
    (token) => process.stdout.write(token),
    (tool) => {
      if (tool.output) {
        console.log(`\n[${tool.name}] Complete`);
      } else {
        console.log(`\n[${tool.name}] Started...`);
      }
    },
    () => {}
  );
  ```

  ```go Go theme={null}
  package main

  import (
      "bufio"
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
      "strings"
  )

  type MCPPlaygroundMessage struct {
      Content         string   `json:"content"`
      MCPInstanceIDs  []string `json:"mcp_instance_ids,omitempty"`
      Model           string   `json:"model,omitempty"`
  }

  type ToolEvent struct {
      ID         string                 `json:"id"`
      Name       string                 `json:"name"`
      Input      map[string]interface{} `json:"input,omitempty"`
      Output     interface{}            `json:"output,omitempty"`
      Successful *bool                  `json:"successful,omitempty"`
      Error      *string                `json:"error,omitempty"`
  }

  type StreamData struct {
      Message string      `json:"message"`
      Tool    *ToolEvent  `json:"tool"`
      Error   string      `json:"error,omitempty"`
      MCP     *MCPRecommendation `json:"mcp,omitempty"`
  }

  type MCPRecommendation struct {
      ServerIDs []string `json:"server_ids"`
  }

  func chatWithMCP(baseURL, token string, msg MCPPlaygroundMessage) error {
      url := fmt.Sprintf("%s/api/mcp_playground/chat", baseURL)

      jsonData, _ := json.Marshal(msg)
      req, _ := http.NewRequest("POST", url, bytes.NewReader(jsonData))
      req.Header.Set("Authorization", "Bearer "+token)
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return err
      }
      defer resp.Body.Close()

      scanner := bufio.NewScanner(resp.Body)
      for scanner.Scan() {
          line := scanner.Text()
          if strings.HasPrefix(line, "data: ") {
              data := strings.TrimPrefix(line, "data: ")

              var streamData StreamData
              if err := json.Unmarshal([]byte(data), &streamData); err == nil {
                  if streamData.Message == "DONE" {
                      fmt.Println("\nStream complete")
                      break
                  }

                  if streamData.Error != "" {
                      return fmt.Errorf("stream error: %s", streamData.Error)
                  }

                  // MCP recommendations
                  if streamData.MCP != nil {
                      fmt.Printf("Recommended servers: %v\n", streamData.MCP.ServerIDs)
                  }

                  // Tool events
                  if streamData.Tool != nil {
                      if streamData.Tool.Output != nil {
                          fmt.Printf("\n[%s] Complete\n", streamData.Tool.Name)
                      } else {
                          fmt.Printf("\n[%s] Started...\n", streamData.Tool.Name)
                      }
                  }

                  // Regular content
                  if streamData.Message != "" && streamData.Message != "DONE" {
                      fmt.Print(streamData.Message)
                  }
              }
          }
      }

      return scanner.Err()
  }

  func main() {
      // Intelligent Discovery Mode
      msgDiscovery := MCPPlaygroundMessage{
          Content: "Show me my urgent emails",
          Model:   "gpt-4-turbo",
      }

      // Direct MCP Mode
      msgDirect := MCPPlaygroundMessage{
          Content: "Forward urgent emails to Slack",
          MCPInstanceIDs: []string{"gmail-id", "slack-id"},
          Model: "claude-3.5-sonnet",
      }

      chatWithMCP("{{baseUrl}}", "YOUR_TOKEN", msgDirect)
  }
  ```

  ```text Streaming Response Format theme={null}
  # Regular message streaming
  data: {"message": "I'll", "tool": null}
  data: {"message": " check", "tool": null}
  data: {"message": " your", "tool": null}
  data: {"message": " emails", "tool": null}
  data: {"message": "...", "tool": null}

  # Tool call started
  data: {"message": "", "tool": {"id": "call_abc", "name": "gmail_list_messages", "input": {"query": "is:urgent", "maxResults": 10}, "output": null}}

  # Tool call completed
  data: {"message": "", "tool": {"id": "call_abc", "name": "gmail_list_messages", "successful": true, "error": null, "input": {...}, "output": {"messages": [...], "nextPageToken": "xyz", "resultSizeEstimate": 45}}}

  # Continued message
  data: {"message": " You", "tool": null}
  data: {"message": " have", "tool": null}
  data: {"message": " 5", "tool": null}
  data: {"message": " urgent", "tool": null}
  data: {"message": " emails", "tool": null}

  # Completion signal
  data: {"message": "DONE", "tool": null}

  # Intelligent Mode - MCP Recommendation
  data: {"message": "To check your emails, I need access to Gmail", "tool": null}
  data: {"mcp": {"server_ids": ["gmail-server-uuid"]}, "message": "", "tool": null}
  data: {"message": "DONE", "tool": null}

  # Error handling
  data: {"error": "Failed to connect to MCP server. Please check the URL and try again."}
  ```
</CodeGroup>

**Endpoint:** `POST /api/mcp_playground/chat`

**Request Body:**

| Field              | Type   | Required | Description                               |
| ------------------ | ------ | -------- | ----------------------------------------- |
| `content`          | string | Yes      | User's message/query                      |
| `mcp_instance_ids` | array  | No       | MCP instance UUIDs to use (Direct Mode)   |
| `model`            | string | No       | LLM model to use (defaults based on mode) |

**Model Options:**

The service accepts any model name starting with the provider prefix. **Hardcoded defaults** are used when no model is specified:

| Model Pattern  | Provider  | Default Behavior                    | Use Case                         |
| -------------- | --------- | ----------------------------------- | -------------------------------- |
| `gpt-*`, `o1*` | OpenAI    | -                                   | General purpose, reasoning       |
| `claude-*`     | Anthropic | -                                   | Tool use, long context           |
| `deepseek-*`   | DeepSeek  | **Intelligent Mode: deepseek-chat** | Database queries, cost-effective |
| `gemini-*`     | Google    | **Direct Mode: gemini-2.5-flash**   | Fast tool execution              |

**How Defaults Work:**

* **Intelligent Discovery Mode** (no `mcp_instance_ids`): Defaults to `deepseek-chat` if `model` not provided
* **Direct MCP Mode** (with `mcp_instance_ids`): Defaults to `gemini-2.5-flash` if `model` not provided

**Response Format:**

Server-Sent Events (SSE) stream with these data types:

### Stream Event Types

#### 1. Message Content

Regular AI response tokens.

```json theme={null}
{
  "message": "text token",
  "tool": null
}
```

#### 2. Tool Call Started

AI initiates a tool call.

```json theme={null}
{
  "message": "",
  "tool": {
    "id": "call_abc123",
    "name": "gmail_list_messages",
    "input": {
      "query": "is:urgent is:unread",
      "maxResults": 10
    },
    "output": null
  }
}
```

#### 3. Tool Call Completed

Tool execution finished.

```json theme={null}
{
  "message": "",
  "tool": {
    "id": "call_abc123",
    "name": "gmail_list_messages",
    "successful": true,
    "error": null,
    "input": {
      "query": "is:urgent is:unread",
      "maxResults": 10
    },
    "output": {
      "messages": [
        {
          "id": "msg123",
          "subject": "Urgent: Project Deadline",
          "from": "boss@company.com",
          "snippet": "Need this by EOD..."
        }
      ],
      "resultSizeEstimate": 45,
      "nextPageToken": "page_token_xyz"
    }
  }
}
```

**Tool Output Fields:**

| Field        | Type    | Description                                  |
| ------------ | ------- | -------------------------------------------- |
| `successful` | boolean | Whether tool executed successfully           |
| `error`      | string  | Error message if failed (null if successful) |
| `output`     | object  | Tool-specific result data                    |

**Pagination Metadata:**

Some tools return pagination information:

| Field                | Type   | Description                       |
| -------------------- | ------ | --------------------------------- |
| `nextPageToken`      | string | Token for next page of results    |
| `resultSizeEstimate` | number | Total number of results available |

The system automatically tracks this metadata and uses it when the user requests "more" results.

#### 4. MCP Server Recommendation

Intelligent Mode suggests servers to connect.

```json theme={null}
{
  "mcp": {
    "server_ids": [
      "gmail-server-uuid",
      "slack-server-uuid"
    ]
  },
  "message": ""
}
```

**Frontend should:**

1. Extract `server_ids`
2. Fetch server details via MCP Service
3. Prompt user to connect servers
4. After connection, resend message with `mcp_instance_ids`

#### 5. Completion Signal

Stream finished.

```json theme={null}
{
  "message": "DONE",
  "tool": null
}
```

#### 6. Error

Stream encountered an error.

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

## Mode Details

### Intelligent Discovery Mode

**Trigger**: No `mcp_instance_ids` provided

**Behavior:**

1. AI analyzes user query
2. Searches database for relevant MCP servers
3. Returns streaming response with recommendations
4. Includes `{"mcp": {"server_ids": [...]}}` in stream

**Example Flow:**

```typescript theme={null}
// User: "Send an email to john@example.com"
await chatWithMCP(
  {
    content: "Send an email to john@example.com",
    model: "deepseek-chat"  // Default for Intelligent Mode
  },
  (token) => display(token),
  () => {},
  (serverIds) => {
    // serverIds = ["gmail-server-uuid"]
    // Prompt user to connect Gmail
    showConnectDialog(serverIds);
  }
);

// After user connects Gmail...
await chatWithMCP(
  {
    content: "Send an email to john@example.com",
    mcp_instance_ids: ["gmail-instance-id"]  // Now in Direct Mode
  },
  (token) => display(token),
  (tool) => showToolExecution(tool),
  () => {}
);
```

**Intelligent Agent Features:**

* **Natural Language Understanding**: Analyzes intent
* **Database Search**: Queries mcp\_servers and mcp\_tools tables
* **Context Awareness**: Uses conversation history (30 exchanges)
* **Smart Recommendations**: Suggests relevant servers only
* **Conversational**: Continues chatting while recommending

### Direct MCP Mode

**Trigger**: `mcp_instance_ids` provided

**Behavior:**

1. Generates MCP URLs for specified instances
2. Connects to all MCP servers
3. Initializes AI agent with multi-MCP tools
4. Streams tool calls and responses
5. Maintains conversation history (16 exchanges)

**Example Flow:**

```typescript theme={null}
// User has connected Gmail and Slack
await chatWithMCP(
  {
    content: "Forward urgent emails to #general channel",
    mcp_instance_ids: ["gmail-instance", "slack-instance"],
    model: "gemini-2.5-flash"  // Fast model for tool use
  },
  (token) => display(token),
  (tool) => {
    if (tool.output === null) {
      // Tool started
      showToolStart(tool.name, tool.input);
    } else {
      // Tool completed
      showToolResult(tool.name, tool.output, tool.successful);
    }
  },
  () => {}
);

// Possible tool sequence:
// 1. gmail_search_messages (query: "is:urgent")
// 2. gmail_get_message (id: "msg123")
// 3. slack_send_message (channel: "general", text: "...")
```

**Multi-MCP Features:**

* **Parallel Connections**: Connect to multiple servers
* **Tool Orchestration**: AI chains tools across servers
* **Context Preservation**: Full conversation history
* **Metadata Tracking**: Pagination tokens preserved
* **XML Prompting**: Structured context for better responses

## Conversation Management

### Memory System

**Conversation Storage:**

* **Intelligent Mode**: 60 messages max (30 exchanges) - hardcoded
* **Direct Mode**: 30 messages - passed as memory\_size parameter to playground factory
* **TTL**: 30 minutes of inactivity (hardcoded)
* **Format**: Chronological array of `{role, content, created_at}`

**Automatic Cleanup:**

```python theme={null}
# Sessions inactive for >30 minutes are cleared
last_active = datetime.now() - timedelta(minutes=30)
if session_last_active < last_active:
    clear_session(session_id)
```

**History Usage:**

The system automatically includes conversation history in each request using structured XML formatting. Each conversation includes user and assistant messages with timestamps, allowing the AI to maintain context across multiple exchanges.

This enables contextual interactions:

* "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

### Tool Metadata Tracking

Pagination tokens and metadata automatically preserved:

```python theme={null}
# After tool completes with pagination
metadata = {
    "nextPageToken": "page_xyz",
    "resultSizeEstimate": 150
}

# Stored for session
factory.add_tool_metadata(session_id, "gmail_list_messages", metadata)

# Used in future calls
# User: "Show me more emails"
# AI automatically uses nextPageToken
```

## Error Handling

### Connection Errors

```json theme={null}
{
  "error": "Failed to connect to MCP server. Please check the URL and try again."
}
```

**Causes:**

* MCP server unavailable
* Invalid MCP URL
* Network issues

**Solutions:**

* Verify MCP instance is active
* Check network connectivity
* Try reconnecting MCP instance

### Timeout Errors

```json theme={null}
{
  "error": "MCP server connection timed out. The server may be unavailable."
}
```

**Causes:**

* MCP server too slow (>30s)
* Heavy computation
* Network latency

**Solutions:**

* Retry request
* Use faster MCP server
* Break into smaller operations

### Tool Errors

```json theme={null}
{
  "message": "",
  "tool": {
    "id": "call_abc",
    "name": "gmail_send_message",
    "successful": false,
    "error": "Insufficient permissions to send emails",
    "input": {...},
    "output": null
  }
}
```

**Common Tool Errors:**

* Insufficient permissions
* Invalid parameters
* Resource not found
* Rate limit exceeded

### No Valid Instances

```json theme={null}
{
  "detail": "No valid MCP instances found for the provided IDs"
}
```

**Causes:**

* Instance IDs don't exist
* Instances not active
* User doesn't own instances

**Solutions:**

* Check instance IDs
* Verify instances are active via `/api/mcp/list_instances`
* Reconnect MCP servers

## Advanced Features

### Multi-Server Orchestration

Chain operations across multiple MCP servers:

```javascript theme={null}
// Example: Email-to-Slack workflow
await chatWithMCP(
  {
    content: "Find emails about 'Project Alpha' and post summary to Slack",
    mcp_instance_ids: ["gmail-id", "slack-id"]
  },
  (token) => display(token),
  (tool) => {
    // Sequence of tools:
    // 1. gmail_search_messages (query: "Project Alpha")
    // 2. gmail_get_message (for each result)
    // 3. slack_send_message (summarized content)
    logToolExecution(tool);
  }
);
```

### Contextual Follow-ups

Leverage conversation history for natural interactions:

```javascript theme={null}
// First query
await chat({ content: "List my Gmail labels" });
// Response: "You have labels: Work, Personal, Important..."

// Follow-up (no need to specify "Gmail")
await chat({ content: "Show emails in the Work label" });
// AI remembers we're working with Gmail

// Another follow-up
await chat({ content: "Send the first one to Slack" });
// AI knows which email to send
```

### Complex Searches

Use comprehensive search strategies:

```javascript theme={null}
await chatWithMCP(
  {
    content: "Find all urgent communications from this week",
    mcp_instance_ids: ["gmail-id", "slack-id"]
  },
  // AI automatically:
  // - Searches Gmail for is:urgent, is:important, from:boss, subject:urgent/ASAP
  // - Searches Slack for mentions, DMs, urgent keywords
  // - Combines and presents results
);
```

## Best Practices

### For Frontend Developers

1. **Handle Both Modes**:
   ```typescript theme={null}
   if (streamData.mcp?.server_ids) {
     // Intelligent Mode - prompt to connect
     showConnectServersDialog(streamData.mcp.server_ids);
   }
   ```

2. **Display Tool Execution**:
   ```typescript theme={null}
   if (tool.output === null) {
     showLoadingIndicator(`Calling ${tool.name}...`);
   } else {
     hideLoadingIndicator();
     if (!tool.successful) {
       showError(tool.error);
     }
   }
   ```

3. **Buffer Message Tokens**:
   ```typescript theme={null}
   let buffer = '';
   onToken((token) => {
     buffer += token;
     if (buffer.length > 50 || token.includes(' ')) {
       display(buffer);
       buffer = '';
     }
   });
   ```

4. **Handle Errors Gracefully**:
   ```typescript theme={null}
   try {
     await chatWithMCP(message);
   } catch (error) {
     if (error.message.includes('No valid MCP instances')) {
       promptReconnect();
     } else {
       showErrorDialog(error.message);
     }
   }
   ```

### For Users

1. **Be Specific**: "Show urgent emails from last week" vs "show emails"
2. **Use Natural Language**: The AI understands intent
3. **Leverage History**: Reference previous messages
4. **Connect Relevant Servers**: Only connect what you'll use
5. **Review Tool Calls**: Understand what the AI is doing

### For Developers

1. **Model Selection**:
   * **Intelligent Mode Default**: `deepseek-chat` (hardcoded, optimized for DB queries)
   * **Direct Mode Default**: `gemini-2.5-flash` (hardcoded, optimized for tool execution)
   * **Override for Quality**: Use `gpt-4`, `o1`, or `claude-3.5-sonnet` for complex reasoning
   * **Override for Context**: Use `claude-3-opus` for long conversations
   * Model string must start with: `gpt`, `o1`, `claude`, `deepseek`, or `gemini`

2. **Instance Management**:
   * Cache active instance IDs
   * Refresh list periodically
   * Handle instance expiration

3. **Error Recovery**:
   * Retry on timeout (once)
   * Fallback to simpler queries
   * Clear instructions on permission errors

## Rate Limiting

* Feature flag: `mcp_sessions` quota
* Concurrent MCP connections: No hard limit (performance degrades)
* Message rate: No explicit limit
* Tool execution timeout: 30 seconds per tool

## Security

* **Authentication**: JWT required
* **RBAC**: `mcp:write` permission required
* **Org Isolation**: Sessions scoped to organizations
* **Data Privacy**: Conversations cleared after 30 minutes
* **Tool Safety**: User owns all MCP connections

## Performance Considerations

### Optimize for Speed

1. **Use Fast Models**:
   * Default `gemini-2.5-flash` for Direct Mode (optimized for tool use)
   * Default `deepseek-chat` for Intelligent Mode (optimized for DB queries)
   * Override with faster models if needed

2. **Limit MCP Servers**:
   * Only connect necessary servers
   * More servers = slower initialization

3. **Reduce History**:
   * Default 30 messages for Direct Mode
   * Reduce memory\_size parameter for faster context loading

4. **Batch Operations**:
   * "Process first 10 emails" vs "Process all"

### Optimize for Quality

1. **Use Reasoning Models**:
   * Override defaults with `gpt-4` or `o1` for complex logic
   * Use `claude-3.5-sonnet` for advanced tool orchestration
   * Defaults are optimized for speed, not quality

2. **Provide Context**:
   * Longer queries = better understanding
   * Reference previous conversations
   * Use conversation history features

3. **Note on History**:
   * Intelligent Mode: Fixed at 30 exchanges
   * Direct Mode: Fixed at 30 messages (memory\_size hardcoded in service)
   * Cannot be increased without code changes

## Next Steps

Continue exploring MCP integration:

* [**MCP Service API**](/pages/api-reference/mcp-service) - Manage MCP connections
* [**MCP Concepts**](/pages/concepts/mcp) - Deep dive into architecture
* [**Chat Service**](/pages/api-reference/chat-service) - Standard chat without MCP
* [**Authentication**](/pages/authentication/overview) - Security and permissions

Ready to build? Check out our [**Quick Start Guide**](/pages/getting-started/quickstart) or explore [**Example Use Cases**](/pages/concepts/mcp#use-cases)!