---
title: MCP
description: Connect Model Context Protocol servers to extend AI capabilities
---

## Overview

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) enables you to connect external servers that expose tools, resources, and prompts to your AI. This lets the AI call custom functions, access data sources, and follow structured workflows specific to your needs.

## Quick Start

Enable MCP in `chat.config.ts`:

```typescript
ai: {
  tools: {
    mcp: {
      enabled: true, // Requires MCP_ENCRYPTION_KEY
    },
  },
}
```

Generate an encryption key (must be exactly 44 characters):

```bash
openssl rand -base64 32
```

Set the environment variable:

```bash
MCP_ENCRYPTION_KEY=your_generated_44_char_key
```

## Configuration

### In chat.config.ts

Enable the integration:

```typescript title="chat.config.ts"
import type { ConfigInput } from "@/lib/config-schema";

const config: ConfigInput = {
  ai: {
    tools: {
      mcp: {
        enabled: true, // Requires MCP_ENCRYPTION_KEY
      },
    },
  },
  // ... rest of config
};

export default config;
```

### Environment Variables

Required (must be exactly 44 characters, base64-encoded 32 bytes):

```bash
MCP_ENCRYPTION_KEY=your_base64_encoded_32_byte_key
```

## Creating Connectors

Add MCP server connectors from the Connectors settings page.

1. Go to Settings → Connectors
2. Click "New Connector"
3. Fill in the connector details:
   - **Name**: A friendly name for your connector (e.g., "My Database Tool")
   - **URL**: The server endpoint (HTTP or SSE)
   - **Type**: Choose `http` or `sse` (Server-Sent Events)
   - **OAuth Credentials** (optional): If the server requires OAuth, provide the client ID and secret

The name you choose becomes the namespace for all tools from that server in the AI.

## Connection Types

**HTTP**

Traditional request-response connections. The AI can call tools and fetch resources on demand.

**SSE (Server-Sent Events)**

Persistent streaming connections. Useful for servers that push updates or maintain state.

## OAuth Authorization

Some MCP servers require OAuth authorization. If a server supports dynamic client registration, the connector setup handles it automatically. For servers requiring pre-configured credentials:

1. Provide your OAuth client ID and secret during connector creation
2. On first connection, you may be asked to authorize access
3. Tokens are securely encrypted and stored in the database

## How It Works

When you connect an MCP server:

1. The connector establishes a connection to the server at the URL you provided
2. The server exposes tools, resources, and prompts to your AI
3. During chat, the AI can call any of these tools as needed
4. The server processes the request and returns the result

Sensitive data (server URLs, OAuth tokens, credentials) is encrypted using your `MCP_ENCRYPTION_KEY` before being stored in the database.

## Managing Connectors

From the Connectors settings page you can:

- **View** all connected servers and their status
- **Enable/Disable** individual connectors without deleting them
- **Update** connector settings (name, URL, type, OAuth credentials)
- **Delete** connectors (removes the connection and all associated data)
- **Disconnect** OAuth sessions if authentication fails

Each connector is scoped to your account. Global connectors (shared across the app) can only be created by administrators.

## Troubleshooting

**Connection Failed**

- Verify the server URL is correct and accessible from your deployment
- Check that the server supports the connection type you selected (HTTP vs SSE)
- For Vercel deployments, ensure the server is publicly accessible (no local URLs)

**OAuth Authorization Fails**

- Verify your OAuth client ID and secret are correct
- Confirm the redirect URI is whitelisted on the server: `https://yourdomain.com/api/mcp/oauth/callback`
- Check that you authorized the requested scopes

**Tools Not Appearing**

- Verify the connector status is "connected" in the Connectors page
- Some servers may require additional configuration to expose tools
- Try disconnecting and reconnecting the server

## Advanced Configuration

### Encryption Security

The `MCP_ENCRYPTION_KEY` protects:

- Server URLs
- OAuth client secrets
- OAuth tokens
- Any credentials stored in the connector

Use a secure, randomly generated key. Never commit it to version control.

### Using with Chat

MCP tools are automatically available in chat conversations. The AI:

1. Sees all tools from connected MCP servers
2. Calls them based on the conversation context
3. Receives and processes results in real-time

No additional configuration is needed in your chat logic.