NocoDB MCP Server

# Native NocoDB MCP Server vs Custom MCP Server

## Overview

NocoDB now has **native MCP Server support** (introduced in 0.265.0+) as documented in the [official MCP documentation](https://nocodb.com/docs/product-docs/mcp). This document compares the native implementation with our custom MCP server.

## Native NocoDB MCP Server

### How It Works

According to the [official documentation](https://nocodb.com/docs/product-docs/mcp):

1. **Base-Specific Endpoints**
   - Each base gets its own MCP endpoint: `https://your-domain.com/mcp/<ncId>`
   - Requires MCP token: `xc-mcp-token: <ncToken>`
   - Generated per base in Settings → Model Context Protocol

2. **Two Integration Methods**

   **Desktop Clients (Claude Desktop, Cursor, Windsurf):**
   ```json
   {
     "mcpServers": {
       "NocoDB MCP": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://your-domain.com/mcp/<ncId>",
           "--header",
           "xc-mcp-token: <ncToken>"
         ]
       }
     }
   }
   ```

   **Web Clients (Claude Web, ChatGPT):**
   - Uses OAuth authentication
   - Endpoint: `https://app.nocodb.com/mcp` (or your self-hosted URL)
   - User selects workspace and base during OAuth flow

3. **Features**
   - ✅ Record-level CRUD operations
   - ✅ Base-specific access
   - ✅ OAuth for web clients
   - ✅ Token-based for desktop clients
   - ❌ Does NOT handle table/field/metadata changes

### Self-Hosted Configuration

From the documentation:
- **Desktop Clients**: Replace `https://app.nocodb.com` with your instance URL
- **Web Clients (OAuth)**: Replace `https://app.nocodb.com` with your self-hosted URL
- **Example**: `https://nocodb.v1su4.com/mcp` for your instance

## Our Custom MCP Server

### How It Works

1. **Single Server for All Bases**
   - One MCP server handles all bases
   - Uses API token authentication (`xc-token` header)
   - Deployed as standalone service

2. **Integration Method**
   ```json
   {
     "mcpServers": {
       "nocodb": {
         "transport": {
           "type": "streamable-http",
           "url": "https://mcp-nocodb.v1su4.com/"
         }
       }
     }
   }
   ```

3. **Features**
   - ✅ Record-level CRUD operations
   - ✅ Cross-base access (all bases in one server)
   - ✅ Table creation (Discord reactions example)
   - ✅ Analytics tools
   - ✅ Custom workflows
   - ✅ Uses API v3 with v2 fallback

## Comparison

| Feature | Native MCP | Custom MCP |
|---------|-----------|------------|
| **Setup** | Per-base configuration | Single server |
| **Authentication** | OAuth (web) or MCP token (desktop) | API token |
| **Base Access** | One base per endpoint | All bases |
| **Table Operations** | ❌ Record-level only | ✅ Includes table creation |
| **Custom Tools** | ❌ Standard CRUD only | ✅ Custom tools (analytics, etc.) |
| **Self-Hosted** | ✅ Supported | ✅ Supported |
| **Deployment** | Built into NocoDB | Separate service |
| **Version Required** | 0.265.0+ | Works with any version |

## When to Use Each

### Use Native MCP When:
- ✅ You want OAuth integration for web clients
- ✅ You need base-specific access control
- ✅ You only need standard CRUD operations
- ✅ You're using NocoDB 0.265.0+
- ✅ You want official NocoDB support

### Use Custom MCP When:
- ✅ You need cross-base operations
- ✅ You want custom tools (analytics, table creation, etc.)
- ✅ You need table/metadata operations
- ✅ You want a single server for all bases
- ✅ You're using older NocoDB versions
- ✅ You need custom workflows

## Self-Hosted Considerations

### Native MCP (Self-Hosted)

1. **Desktop Clients:**
   ```json
   {
     "mcpServers": {
       "NocoDB MCP": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://nocodb.v1su4.com/mcp/<ncId>",
           "--header",
           "xc-mcp-token: <ncToken>"
         ]
       }
     }
   }
   ```

2. **Web Clients (OAuth):**
   - Use: `https://nocodb.v1su4.com/mcp`
   - OAuth flow will use your self-hosted instance

3. **Getting MCP Endpoint:**
   - Go to: Base → Settings → Model Context Protocol
   - Click "New MCP Endpoint"
   - Copy the generated JSON config

### Custom MCP (Self-Hosted)

Already configured for your instance:
- **URL**: `https://mcp-nocodb.v1su4.com/`
- **Authentication**: Uses `NOCODB_API_TOKEN` environment variable
- **NocoDB URL**: `https://nocodb.v1su4.com`
- **API Version**: v3 primary, v2 fallback

## Recommendation for Your Setup

### Option 1: Use Both (Recommended)

**Native MCP for:**
- Web-based LLM clients (Claude Web, ChatGPT) via OAuth
- Base-specific access when needed

**Custom MCP for:**
- Desktop clients (Claude Desktop, Cursor)
- Cross-base operations
- Custom tools and workflows
- Table creation and analytics

### Option 2: Migrate to Native MCP

If you only need standard CRUD:
1. Upgrade to NocoDB 0.265.0+
2. Generate MCP endpoints per base
3. Configure clients with native endpoints
4. Remove custom MCP server

### Option 3: Keep Custom MCP Only

If you need custom features:
- Continue using custom MCP server
- Native MCP is optional
- Both can coexist

## Action Items

1. ✅ **Documentation Updated** - This comparison document
2. ⏳ **Test Native MCP** - Try native MCP with your self-hosted instance
3. ⏳ **Decide Strategy** - Choose native, custom, or both
4. ⏳ **Update Client Configs** - If switching to native MCP

## References

- [NocoDB Official MCP Documentation](https://nocodb.com/docs/product-docs/mcp)
- [NocoDB 0.265.0 Release](https://github.com/nocodb/nocodb/releases) - Native MCP introduction
- [Our Custom MCP Server](../README.md) - Current implementation