MCP Integration

The chat UI supports Model Context Protocol (MCP) for connecting to external tool servers. MCP enables LLMs to access tools, resources, and prompts from any compatible server, extending capabilities beyond built-in frontend tools.

Overview

MCP integration runs entirely in the browser, connecting to external MCP servers via HTTP. When you connect to an MCP server, its tools become available to models during chat sessions.

Key capabilities:

• Connect to multiple MCP servers simultaneously
• Automatic tool discovery from connected servers
• Per-server and per-tool enable/disable controls
• Persistent server configuration across sessions
• Real-time connection status monitoring

Transport

The implementation uses the Streamable HTTP transport (MCP specification 2025-03-26), which provides:

Adding a Server

Via the UI

1. Click the Tools button in the chat input toolbar
2. Click Configure next to MCP Servers (or the plug icon)
3. Click Add Server
4. Fill in the server details:

Authentication Headers

For servers requiring authentication, add headers as a JSON object:

{
  "Authorization": "Bearer your-api-key",
  "X-Custom-Header": "value"
}

Common authentication patterns:

Connecting to Servers

After adding a server, click Connect to establish a session. The connection process:

1. Initialize handshake (protocol version, capabilities)
2. Server returns session ID and available capabilities
3. Client sends initialized notification
4. SSE stream opened for server notifications
5. Tool discovery via tools/list
6. Status changes to "connected"

Connection Status

Servers auto-reconnect if the SSE stream drops. Manual reconnection is available via the Connect button.

Tool Discovery

Once connected, the client automatically discovers available tools:

// Example discovered tools from a GitHub MCP server
[
  {
    name: "search_repos",
    description: "Search GitHub repositories",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
        sort: { type: "string", enum: ["stars", "forks", "updated"] }
      },
      required: ["query"]
    }
  },
  {
    name: "create_issue",
    description: "Create a GitHub issue",
    inputSchema: { ... }
  }
]

Managing Tools

Each tool can be individually enabled or disabled:

1. Expand a connected server in the MCP configuration modal
2. Toggle individual tools on/off
3. Disabled tools are not sent to the model

Tool preferences persist across sessions in localStorage.

Using MCP Tools in Chat

Enabling MCP

1. Click Tools in the chat input toolbar
2. Enable MCP Servers
3. Ensure at least one server is connected with enabled tools

Tool Registration

When MCP is enabled, tools from connected servers are automatically added to the model's available functions. Tools use namespaced names to prevent conflicts:

Format: mcp_{serverId}_{toolName}

Examples:
- mcp_github-server_search_repos
- mcp_github-server_create_issue
- mcp_slack-server_send_message

The model sees tools with descriptions prefixed by the server name:

[MCP: GitHub Tools] Search GitHub repositories

Execution Flow

1. User sends message with MCP enabled
2. Model decides to call an MCP tool
3. Frontend parses tool name to extract server ID and tool name
4. Request sent to MCP server via tools/call
5. Server executes tool and returns result
6. Result formatted and sent back to model
7. Model continues with tool result

Tool Results

MCP tools can return multiple content types:

Example tool result:

{
  "content": [
    {
      "type": "text",
      "text": "Found 50 repositories:\n1. facebook/react (220k stars)..."
    }
  ],
  "isError": false
}

Configuration

Server Configuration

Server configurations are persisted to localStorage:

interface MCPServerConfig {
  id: string; // Auto-generated unique ID
  name: string; // Display name
  url: string; // HTTP endpoint
  enabled: boolean; // Whether server is active
  headers?: {
    // Optional auth headers
    [key: string]: string;
  };
  toolsEnabled: {
    // Per-tool enable state
    [toolName: string]: boolean;
  };
}

Client Settings

Persisted vs Ephemeral State

Protocol Support

Client Capabilities

The client advertises these capabilities to servers:

{
  "tools": { "progress": false },
  "resources": { "subscribe": false }
}

Supported Methods

Notification Types

The client handles these server notifications via SSE:

Error Handling

Connection Errors

Connection errors are displayed in the UI with the error message visible on hover.

Tool Execution Errors

When a tool fails, the error is returned to the model:

{
  "success": false,
  "error": "Repository not found",
  "output": "{\"error\": \"Repository not found\", \"serverId\": \"github\", \"toolName\": \"get_repo\"}"
}

The model can then handle the error appropriately (retry, ask for clarification, etc.).

Example Workflow

1. Set Up a GitHub MCP Server

Name: GitHub Tools
URL: https://your-mcp-server.com/github
Headers: {"Authorization": "Bearer ghp_xxxx"}

2. Connect and Discover Tools

After connecting, you see:

• search_repos - Search GitHub repositories
• get_repo - Get repository details
• create_issue - Create an issue
• list_issues - List repository issues

3. Use in Chat

User: Find popular React component libraries on GitHub

Model: I'll search GitHub for React component libraries.

Calls mcp_github-tools_search_repos with:

{
  "query": "react components library stars:>1000",
  "sort": "stars"
}

Tool Result:

Found 25 repositories:
1. chakra-ui/chakra-ui (35k stars) - Simple, modular component library
2. shadcn/ui (45k stars) - Beautifully designed components
3. ant-design/ant-design (88k stars) - Enterprise UI design language
...

Model: Here are the most popular React component libraries on GitHub...

Comparison with Frontend Tools

Use frontend tools for general computation and data analysis. Use MCP for external integrations, file system access, database queries, and custom enterprise tools.

Security Considerations

Server Trust

MCP servers can execute arbitrary actions. Only connect to trusted servers:

• Verify the server URL is legitimate
• Use HTTPS for all connections
• Review available tools before enabling

Credential Storage

Authentication headers are stored in localStorage:

• Accessible to JavaScript on the same origin
• Consider using short-lived tokens where possible
• Clear server configurations when using shared computers

Network Security

• All requests use the configured URL directly
• No server-side proxy (requests go from browser to MCP server)
• CORS must be configured on the MCP server to allow browser requests

Troubleshooting

Server won't connect

1. Check URL: Ensure the endpoint is correct and accessible
2. Check CORS: Server must allow requests from your origin
3. Check auth: Verify authentication headers are correct
4. Check network: Try accessing the URL directly in browser

Tools not appearing

1. Check connection: Ensure status shows "Connected"
2. Check capabilities: Server must advertise tool support
3. Check tool list: Server's tools/list must return tools

Tool execution fails

1. Check arguments: Ensure model is providing valid inputs
2. Check server logs: Review MCP server for error details
3. Check timeout: Long-running tools may need longer timeouts

SSE notifications not working

1. Check browser console: Look for EventSource errors
2. Check server support: Server must support GET requests for SSE
3. Notifications are optional: Core functionality works without them