> ## Documentation Index
> Fetch the complete documentation index at: https://reedai-07fa30f1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Extensions

> Extend ZeroTwo with custom tools, MCP servers, and integrations

## Custom Extensions Overview

Custom extensions allow you to add specialized capabilities to ZeroTwo beyond the built-in tools. Create custom integrations, connect proprietary systems, or leverage Model Context Protocol (MCP) servers for advanced functionality.

<Note>
  Custom extensions are available on Pro, Team, and Enterprise plans. Enterprise plans include advanced features like custom MCP server hosting and private tool registries.
</Note>

## What Are Custom Extensions?

Custom extensions are tools that extend ZeroTwo's capabilities:

<CardGroup cols={2}>
  <Card title="MCP Servers" icon="server">
    Connect to Model Context Protocol servers for standardized integrations
  </Card>

  <Card title="Custom Tools" icon="wrench">
    Build your own tools with custom logic and API connections
  </Card>

  <Card title="API Integrations" icon="plug">
    Connect to proprietary or third-party APIs
  </Card>

  <Card title="Internal Systems" icon="building">
    Access your company's databases, CRMs, or custom platforms
  </Card>
</CardGroup>

## Model Context Protocol (MCP)

MCP is an open protocol that standardizes how AI systems connect to data sources and tools.

### What is MCP?

**Model Context Protocol** provides:

* Standardized communication between AI and external systems
* Reusable server implementations
* Secure, controlled access to resources
* Community-driven ecosystem of integrations

<Info>
  MCP was created by Anthropic and is supported by ZeroTwo natively. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io).
</Info>

### MCP Architecture

```
┌─────────────┐         ┌─────────────┐         ┌──────────────┐
│  ZeroTwo    │ ◄─MCP──►│ MCP Server  │ ◄──────►│ Data Source  │
│  (Client)   │         │             │         │ (API/DB/etc) │
└─────────────┘         └─────────────┘         └──────────────┘
```

**Components**:

* **Client**: ZeroTwo (requests resources/tools)
* **Server**: MCP server (provides capabilities)
* **Resources**: Data, files, system access

### Built-in MCP Servers

ZeroTwo includes pre-configured MCP servers:

<Tabs>
  <Tab title="GitHub">
    **Access GitHub repositories**

    **Capabilities**:

    * Read repository contents
    * Browse file structures
    * View commits and history
    * Read issues and pull requests
    * Search code across repos

    **Setup**: Connect your GitHub account in Settings > Integrations

    **Example use**:

    ```
    Show me the recent commits in the main branch of my project
    ```
  </Tab>

  <Tab title="Linear">
    **Manage Linear issues**

    **Capabilities**:

    * List issues and projects
    * Create new issues
    * Update issue status
    * Add comments
    * Search issues

    **Setup**: Connect Linear in Settings > Integrations

    **Example use**:

    ```
    Create a Linear issue for the authentication bug we discussed
    ```
  </Tab>

  <Tab title="Notion">
    **Access Notion workspace**

    **Capabilities**:

    * Read pages and databases
    * Search content
    * Query databases
    * List workspaces

    **Setup**: Connect Notion in Settings > Integrations

    **Example use**:

    ```
    Search my Notion workspace for documentation about the API
    ```
  </Tab>

  <Tab title="Supabase">
    **Query Supabase projects**

    **Capabilities**:

    * Execute SQL queries
    * Manage tables
    * Access storage
    * View auth users
    * Monitor logs

    **Setup**: Connect Supabase project in Settings > Integrations

    **Example use**:

    ```
    Show me the users table schema from my Supabase project
    ```
  </Tab>
</Tabs>

## Adding Custom MCP Servers

Connect your own MCP servers to ZeroTwo.

### Using Public MCP Servers

<Steps>
  <Step title="Find MCP server">
    Browse available MCP servers:

    * [MCP Server Registry](https://github.com/modelcontextprotocol/servers)
    * Community implementations
    * Official vendor servers
  </Step>

  <Step title="Get server details">
    You'll need:

    * Server URL or command
    * Authentication method
    * Required permissions

    **Example server config**:

    ```json theme={null}
    {
      "name": "weather-server",
      "url": "https://mcp.weather-api.com",
      "auth": "bearer",
      "token": "your-api-key"
    }
    ```
  </Step>

  <Step title="Add to ZeroTwo">
    Navigate to **Settings > Integrations > MCP Servers**

    Click **+ Add MCP Server**
  </Step>

  <Step title="Configure server">
    **Server Details**:

    * **Name**: Friendly name for the server
    * **URL**: Server endpoint
    * **Authentication**: Choose auth method
    * **API Key**: If required

    **Permissions**:

    * Select which resources the server can access
    * Choose allowed operations
    * Set usage limits
  </Step>

  <Step title="Test connection">
    Click **Test Connection** to verify

    <Check>
      If successful, the server is ready to use!
    </Check>
  </Step>

  <Step title="Use in conversations">
    The MCP server's capabilities are now available to AI

    **Example**:

    ```
    What's the weather forecast for San Francisco this week?
    ```

    AI will automatically use your weather MCP server.
  </Step>
</Steps>

### Self-Hosted MCP Servers

Run MCP servers on your own infrastructure:

<Tabs>
  <Tab title="Local Development">
    **Run MCP server locally**:

    <Steps>
      <Step title="Install server">
        ```bash theme={null}
        npm install -g @modelcontextprotocol/server-example
        ```
      </Step>

      <Step title="Start server">
        ```bash theme={null}
        mcp-server start --port 3000
        ```
      </Step>

      <Step title="Expose with ngrok">
        ```bash theme={null}
        ngrok http 3000
        ```

        Copy the public URL
      </Step>

      <Step title="Add to ZeroTwo">
        Use the ngrok URL in ZeroTwo's MCP server settings
      </Step>
    </Steps>

    <Warning>
      Local servers stop when your computer sleeps. Use cloud hosting for production.
    </Warning>
  </Tab>

  <Tab title="Cloud Deployment">
    **Deploy MCP server to cloud**:

    **Options**:

    * Vercel/Netlify Functions
    * AWS Lambda
    * Google Cloud Run
    * Digital Ocean
    * Your own VPS

    **Example Vercel deployment**:

    ```bash theme={null}
    # Deploy MCP server
    vercel deploy

    # Get deployment URL
    https://your-mcp-server.vercel.app
    ```

    Use the deployment URL in ZeroTwo.
  </Tab>

  <Tab title="Docker Container">
    **Run in Docker**:

    ```dockerfile theme={null}
    FROM node:18-alpine

    WORKDIR /app
    COPY package*.json ./
    RUN npm install
    COPY . .

    EXPOSE 3000
    CMD ["npm", "start"]
    ```

    ```bash theme={null}
    # Build and run
    docker build -t my-mcp-server .
    docker run -p 3000:3000 my-mcp-server
    ```

    Deploy container to your preferred platform.
  </Tab>
</Tabs>

### Creating Custom MCP Servers

Build your own MCP server from scratch.

<Steps>
  <Step title="Set up project">
    ```bash theme={null}
    npm init -y
    npm install @modelcontextprotocol/sdk express
    ```
  </Step>

  <Step title="Create server">
    ```javascript server.js theme={null}
    const { MCPServer } = require('@modelcontextprotocol/sdk');
    const express = require('express');

    const app = express();
    const server = new MCPServer({
      name: 'my-custom-server',
      version: '1.0.0'
    });

    // Define a custom tool
    server.addTool({
      name: 'get-user-data',
      description: 'Fetch user data from internal database',
      parameters: {
        type: 'object',
        properties: {
          userId: {
            type: 'string',
            description: 'User ID to fetch'
          }
        },
        required: ['userId']
      },
      handler: async ({ userId }) => {
        // Your custom logic here
        const userData = await fetchFromDatabase(userId);
        return {
          success: true,
          data: userData
        };
      }
    });

    // Mount MCP server
    app.use('/mcp', server.middleware());

    app.listen(3000, () => {
      console.log('MCP server running on port 3000');
    });
    ```
  </Step>

  <Step title="Add resources">
    ```javascript theme={null}
    // Provide access to resources
    server.addResource({
      uri: 'db://users',
      name: 'User Database',
      description: 'Access to user records',
      mimeType: 'application/json',
      handler: async () => {
        const users = await getAllUsers();
        return JSON.stringify(users);
      }
    });
    ```
  </Step>

  <Step title="Implement authentication">
    ```javascript theme={null}
    server.setAuthHandler(async (token) => {
      // Validate API key
      const isValid = await validateToken(token);
      return isValid;
    });
    ```
  </Step>

  <Step title="Deploy and connect">
    Deploy your server and add it to ZeroTwo
  </Step>
</Steps>

<Info>
  See the [MCP Server Documentation](https://modelcontextprotocol.io/docs) for complete implementation guides.
</Info>

## Custom API Tools

Create custom tools that call your APIs.

### Simple API Tool

<Steps>
  <Step title="Define API endpoint">
    Your API endpoint that ZeroTwo will call:

    ```
    POST https://api.yourcompany.com/zerotwo-tools
    ```

    **Request format**:

    ```json theme={null}
    {
      "tool": "get_inventory",
      "parameters": {
        "product_id": "12345"
      }
    }
    ```

    **Response format**:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "product": "Widget",
        "quantity": 150,
        "location": "Warehouse A"
      }
    }
    ```
  </Step>

  <Step title="Add in ZeroTwo">
    Settings > Integrations > Custom Tools > **+ Add Custom Tool**
  </Step>

  <Step title="Configure tool">
    **Tool Configuration**:

    * **Name**: `get_inventory`
    * **Description**: "Check inventory levels for products"
    * **API Endpoint**: Your API URL
    * **Method**: POST
    * **Authentication**: Bearer token / API key

    **Parameters Schema**:

    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "product_id": {
          "type": "string",
          "description": "Product SKU or ID"
        }
      },
      "required": ["product_id"]
    }
    ```
  </Step>

  <Step title="Test tool">
    Use the test interface to verify:

    ```
    Input: { "product_id": "12345" }
    Expected: Successful inventory data retrieval
    ```
  </Step>

  <Step title="Use in conversation">
    AI can now use your custom tool:

    **User**: "Check inventory for product 12345"

    **AI**: Uses `get_inventory` tool → Returns inventory info
  </Step>
</Steps>

### Advanced Tool Configuration

<AccordionGroup>
  <Accordion title="Request customization">
    **Headers**:

    ```json theme={null}
    {
      "Authorization": "Bearer ${API_KEY}",
      "Content-Type": "application/json",
      "X-Custom-Header": "value"
    }
    ```

    **Query parameters**:

    ```json theme={null}
    {
      "format": "json",
      "version": "2"
    }
    ```

    **Request transformation**:
    Map ZeroTwo parameters to your API format.
  </Accordion>

  <Accordion title="Response processing">
    **Response mapping**:

    ```json theme={null}
    {
      "success": "$.status",
      "data": "$.result.data",
      "message": "$.result.message"
    }
    ```

    **Error handling**:

    ```json theme={null}
    {
      "error_path": "$.error",
      "retry_on": [429, 503],
      "max_retries": 3
    }
    ```

    **Data transformation**:
    Transform API response to AI-friendly format.
  </Accordion>

  <Accordion title="Rate limiting">
    **Configure limits**:

    * Requests per minute
    * Requests per hour
    * Burst allowance
    * Cooldown period

    **Example**:

    ```json theme={null}
    {
      "rate_limit": {
        "requests_per_minute": 60,
        "requests_per_hour": 1000,
        "burst": 10
      }
    }
    ```
  </Accordion>

  <Accordion title="Caching">
    **Cache responses**:

    * TTL (time to live)
    * Cache key strategy
    * Invalidation rules

    **Example**:

    ```json theme={null}
    {
      "cache": {
        "enabled": true,
        "ttl": 300,
        "key": "product_${product_id}"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Database Connections (Enterprise)

Connect directly to databases.

<Tabs>
  <Tab title="SQL Databases">
    **Supported databases**:

    * PostgreSQL
    * MySQL
    * SQL Server
    * Oracle
    * SQLite

    **Configuration**:

    ```json theme={null}
    {
      "type": "postgresql",
      "host": "db.yourcompany.com",
      "port": 5432,
      "database": "production",
      "username": "readonly_user",
      "password": "${DB_PASSWORD}",
      "ssl": true
    }
    ```

    **Safety features**:

    * Read-only by default
    * Query allowlist
    * Row limits
    * Timeout controls

    <Warning>
      Always use read-only credentials and limit data access.
    </Warning>
  </Tab>

  <Tab title="NoSQL Databases">
    **Supported**:

    * MongoDB
    * Redis
    * Elasticsearch
    * DynamoDB

    **MongoDB example**:

    ```json theme={null}
    {
      "type": "mongodb",
      "connection_string": "mongodb+srv://...",
      "database": "app_data",
      "collections": ["users", "products"],
      "read_only": true
    }
    ```
  </Tab>

  <Tab title="Data Warehouses">
    **Supported**:

    * Snowflake
    * BigQuery
    * Redshift
    * Databricks

    **Snowflake example**:

    ```json theme={null}
    {
      "type": "snowflake",
      "account": "xy12345",
      "warehouse": "COMPUTE_WH",
      "database": "ANALYTICS",
      "schema": "PUBLIC",
      "role": "READONLY"
    }
    ```
  </Tab>
</Tabs>

## Extension Marketplace

Browse and install community extensions.

### Finding Extensions

**Extension sources**:

* ZeroTwo Extension Marketplace (built-in)
* GitHub MCP Server Registry
* NPM packages
* Community forums

**Categories**:

* 📊 Data & Analytics
* 🔧 Development Tools
* 🤝 CRM & Sales
* 📝 Productivity
* 🎨 Creative Tools
* 🔐 Security & Compliance

### Installing from Marketplace

<Steps>
  <Step title="Browse marketplace">
    Settings > Integrations > **Extension Marketplace**
  </Step>

  <Step title="Search or browse">
    Find extensions by:

    * Category
    * Popularity
    * Recently added
    * Search term
  </Step>

  <Step title="View details">
    Click extension to see:

    * Description and capabilities
    * Required permissions
    * Reviews and ratings
    * Installation instructions
    * Pricing (if applicable)
  </Step>

  <Step title="Install">
    Click **Install Extension**

    Review and approve permissions
  </Step>

  <Step title="Configure">
    Set up API keys or connection details as needed
  </Step>

  <Step title="Activate">
    Enable the extension for your projects
  </Step>
</Steps>

## Managing Extensions

Keep your extensions organized and secure.

### Extension Settings

**For each extension**:

* ✅ Enable/disable
* ⚙️ Configuration
* 🔐 Permissions
* 📊 Usage statistics
* 🔄 Update status
* 🗑️ Uninstall

**Access**: Settings > Integrations > Manage Extensions

### Permissions Management

<AccordionGroup>
  <Accordion title="Review permissions">
    **What extensions can access**:

    * Conversation history
    * File uploads
    * API credentials
    * Project data
    * Personal information

    **Permission levels**:

    * 👀 Read-only
    * ✏️ Read-write
    * 🔐 Sensitive data access
    * 🌐 Network access
  </Accordion>

  <Accordion title="Revoke permissions">
    Remove specific permissions without uninstalling:

    1. Open extension settings
    2. Click **Permissions**
    3. Toggle off unwanted permissions
    4. Extension functionality may be limited
  </Accordion>

  <Accordion title="Audit log">
    **Track extension activity**:

    * API calls made
    * Data accessed
    * Errors encountered
    * Performance metrics

    **Access**: Extension Settings > Activity Log
  </Accordion>
</AccordionGroup>

### Updating Extensions

**Auto-updates** (default):

* Extensions update automatically
* Security patches applied immediately
* Breaking changes delayed with notice

**Manual updates**:

1. Settings > Extensions
2. See "Update Available" badge
3. Review changelog
4. Click **Update**

<Tip>
  Enable auto-updates for security patches, but review feature updates manually.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Security first">
    **Protect your data**:

    ✅ **Do**:

    * Use read-only database connections
    * Implement proper authentication
    * Review extension permissions regularly
    * Use environment variables for secrets
    * Audit extension activity logs
    * Keep extensions updated

    ❌ **Don't**:

    * Grant unnecessary permissions
    * Hard-code API keys
    * Skip security reviews
    * Trust unverified extensions
    * Expose production databases without limits
  </Accordion>

  <Accordion title="Test thoroughly">
    **Before deploying to production**:

    1. Test in development environment
    2. Verify error handling
    3. Check rate limits
    4. Validate data transformations
    5. Test authentication failures
    6. Monitor performance

    **Use test projects** for initial integration.
  </Accordion>

  <Accordion title="Monitor usage">
    **Track extension performance**:

    * API call counts
    * Response times
    * Error rates
    * Cost (if applicable)
    * User feedback

    **Set alerts** for unusual activity or errors.
  </Accordion>

  <Accordion title="Document integrations">
    **Maintain documentation**:

    * Purpose of each extension
    * Required setup steps
    * Known limitations
    * Troubleshooting guide
    * Contact for issues

    Share with team members for smooth onboarding.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension not working">
    **Common issues**:

    1. **Authentication failed**
       * Verify API keys are correct
       * Check token hasn't expired
       * Ensure proper permissions
    2. **Connection timeout**
       * Check server URL
       * Verify network access
       * Look for firewall blocks
    3. **Invalid response**
       * Check API endpoint is correct
       * Verify response format matches config
       * Look at error logs

    **Debug steps**:

    * Test extension with simple request
    * Check extension activity log
    * Verify API directly (Postman/curl)
    * Contact extension developer
  </Accordion>

  <Accordion title="Permission denied">
    **Resolve access issues**:

    1. Check extension has required permissions
    2. Verify your account has necessary role
    3. Review organization policies
    4. Check if extension is approved

    **Request access**: Contact organization admin if needed.
  </Accordion>

  <Accordion title="MCP server connection failed">
    **Troubleshoot MCP connection**:

    1. Verify server is running
    2. Check URL/endpoint is correct
    3. Test authentication credentials
    4. Look for SSL/TLS issues
    5. Check server logs

    **Test connection**: Use MCP inspector tool to debug.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tool Permissions" icon="shield" href="/tools/permissions-and-privacy">
    Learn about tool security and privacy
  </Card>

  <Card title="MCP Overview" icon="server" href="/integrations/mcp-overview">
    Deep dive into Model Context Protocol
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Build custom integrations with our API
  </Card>

  <Card title="GitHub Integration" icon="github" href="/integrations/github">
    Connect GitHub MCP server
  </Card>
</CardGroup>

<Check>
  Custom extensions unlock unlimited possibilities - connect ZeroTwo to any system or data source!
</Check>