# Self-Hosted Native MCP Server Setup
## Overview
NocoDB's native MCP Server (0.265.0+) works with self-hosted instances. This guide shows how to configure it for your instance at `nocodb.v1su4.com`.
## Prerequisites
- ✅ NocoDB 0.265.0+ installed
- ✅ Self-hosted instance accessible at `https://nocodb.v1su4.com`
- ✅ Base created in NocoDB
## Setup Steps
### 1. Generate MCP Endpoint in NocoDB
1. Log into your NocoDB instance: `https://nocodb.v1su4.com`
2. Select a base (e.g., "KEDB-SOLO")
3. Click **Overview** in left sidebar
4. Go to **Settings** tab
5. Select **Model Context Protocol**
6. Click **New MCP Endpoint**
7. Provide a name (e.g., "KEDB-SOLO MCP")
8. Click **Create**
9. Copy the generated JSON configuration
### 2. Generated JSON Format
The generated JSON will look like:
```json
{
"mcpServers": {
"NocoDB MCP": {
"command": "npx",
"args": [
"mcp-remote",
"https://nocodb.v1su4.com/mcp/<ncId>",
"--header",
"xc-mcp-token: <ncToken>"
]
}
}
}
```
**Note**: The `<ncId>` and `<ncToken>` are base-specific and generated automatically.
### 3. Configure Desktop Clients
#### Claude Desktop
1. Open Claude Desktop Preferences (`⌘+,` or `Ctrl+,`)
2. Under **Develop**, click **Edit Config**
3. Add the JSON block from step 1
4. Save and restart Claude Desktop
#### Cursor
1. Go to **Cursor Settings** (`⇧+⌘+J` or `Shift+Ctrl+J`)
2. Open the **MCP** tab
3. Click **Add Custom MCP**
4. Paste the JSON block from step 1
5. Save
**Expected Result**: You should see "11 tools enabled" below the MCP Server.
#### Windsurf
1. Open **Windsurf Settings** (`⌘+,` or `Ctrl+,`)
2. Go to **Cascade** section → **Plugins (MCP Server)** → **Manage Plugins**
3. Paste the JSON block from step 1
4. Save
### 4. Configure Web Clients (OAuth)
#### Claude Web
1. Go to [Claude Web Settings](https://claude.ai/settings/connectors)
2. Click **Add custom connector**
3. Enter:
- **Name**: Your choice (e.g., "NocoDB Self-Hosted")
- **MCP endpoint URL**: `https://nocodb.v1su4.com/mcp`
- Click **Add**
4. Click **Connect** to start OAuth flow
5. Log in to NocoDB (if needed)
6. Select workspace and base
7. Review permissions and click **Authorize**
#### ChatGPT
1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors)
2. Enable **Developer Mode** in Advanced Settings
3. Click **Create** button
4. Enter:
- **Name**: Your choice
- **MCP Server URL**: `https://nocodb.v1su4.com/mcp`
- Check **I trust this application**
- Click **Create**
5. Complete OAuth authorization flow
## Key Differences: Self-Hosted vs Cloud
| Aspect | Cloud (app.nocodb.com) | Self-Hosted (your instance) |
|--------|------------------------|----------------------------|
| **MCP Endpoint** | `https://app.nocodb.com/mcp` | `https://nocodb.v1su4.com/mcp` |
| **Desktop Config** | Uses `app.nocodb.com` | Replace with your domain |
| **OAuth URL** | `https://app.nocodb.com/mcp` | `https://nocodb.v1su4.com/mcp` |
| **Setup** | Same process | Same process |
## Security Considerations
⚠️ **Important**: MCP configurations function as access credentials with full control over your base.
1. **Never commit to source control**
2. **Store securely** (password manager, secure notes)
3. **Rotate tokens** if compromised
4. **Use base-specific tokens** (native MCP does this automatically)
5. **Review permissions** before authorizing OAuth
## Troubleshooting
### Issue: "Connection failed" or "Invalid endpoint"
**Check:**
- ✅ NocoDB version is 0.265.0+
- ✅ Instance is accessible: `https://nocodb.v1su4.com`
- ✅ MCP endpoint URL uses your domain (not `app.nocodb.com`)
- ✅ Token is correct (copy from NocoDB settings)
### Issue: OAuth flow fails
**Check:**
- ✅ Instance URL is correct: `https://nocodb.v1su4.com/mcp`
- ✅ HTTPS is enabled (required for OAuth)
- ✅ Network connectivity from browser to instance
- ✅ NocoDB version supports OAuth (0.265.0+)
### Issue: "No tools enabled"
**Check:**
- ✅ JSON configuration is valid
- ✅ MCP endpoint URL is correct
- ✅ Token is included in headers
- ✅ Base has tables (MCP needs tables to expose tools)
## Comparison with Custom MCP
| Feature | Native MCP | Custom MCP |
|---------|-----------|------------|
| **Setup** | Per-base | Single server |
| **URL** | `https://nocodb.v1su4.com/mcp/<ncId>` | `https://mcp-nocodb.v1su4.com/` |
| **Auth** | MCP token or OAuth | API token |
| **Bases** | One per endpoint | All bases |
| **Tools** | Standard CRUD | Custom tools |
See [NATIVE_MCP_VS_CUSTOM.md](NATIVE_MCP_VS_CUSTOM.md) for detailed comparison.
## Next Steps
1. ✅ **Generate MCP Endpoint** - Create endpoint in NocoDB settings
2. ⏳ **Configure Client** - Add to Claude Desktop, Cursor, or Windsurf
3. ⏳ **Test Connection** - Verify tools are enabled
4. ⏳ **Set Up OAuth** - Configure web clients if needed
## References
- [Official NocoDB MCP Documentation](https://nocodb.com/docs/product-docs/mcp)
- [NocoDB 0.265.0 Release](https://github.com/nocodb/nocodb/releases) - Native MCP introduction
- [Native vs Custom MCP Comparison](NATIVE_MCP_VS_CUSTOM.md)
