# 🔑 NocoDB API Setup Guide - Home Server Instance
## 📋 Complete Setup for Self-Hosted NocoDB with MCP Integration
### **🎯 Purpose:**
This guide documents the **correct API authentication setup** for NocoDB instances running on home servers, specifically optimized for the Discord Heart Reactions MCP workflow.
---
## 🏠 Home Server NocoDB Configuration
### **✅ Verified Working Setup:**
#### **1. Instance Details:**
- **URL**: `https://nocodb.v1su4.com`
- **Type**: Self-hosted PostgreSQL instance
- **Status**: ✅ Active and operational
#### **2. Authentication Method:**
```bash
# ❌ INCORRECT (Common mistake)
curl -H "xc-auth: token_here" https://nocodb.v1su4.com/api/v1/db/meta/projects
# ❌ INCORRECT (Another common mistake)
curl -H "Authorization: Bearer token_here" https://nocodb.v1su4.com/api/v1/db/meta/projects
# ✅ CORRECT (As per NocoDB API documentation)
curl -H "xc-token: token_here" https://nocodb.v1su4.com/api/v1/db/meta/projects
```
#### **3. Token Generation:**
1. Login to NocoDB: `nocodb.v1su4.com`
2. Navigate: **Account Settings** → **Tokens**
3. Click: **Generate New Token**
4. **Copy the exact token** (format: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`)
---
## 🔧 MCP Server Integration
### **✅ Working MCP Configuration:**
#### **1. Server Architecture:**
```
Claude Code → FastMCP Server (https://mcp-nocodb.v1su4.com) → NocoDB API (https://nocodb.v1su4.com)
```
#### **2. Environment Variables:**
```bash
# Required for MCP Server (in Coolify)
NOCODB_API_TOKEN=your_nocodb_token_here
NOCODB_URL=https://nocodb.v1su4.com
PORT=3001
PYTHONUNBUFFERED=1
```
#### **3. Claude Code MCP Configuration:**
```json
{
"mcpServers": {
"nocodb": {
"transport": {
"type": "streamable-http",
"url": "https://mcp-nocodb.v1su4.com/"
}
}
}
}
```
---
## 🧪 Testing & Validation
### **✅ Token Testing Script:**
```bash
# Download and run the validation script
curl -s https://raw.githubusercontent.com/gordo-v1su4/mcp-server/main/test-nocodb-token.sh > test-token.sh
chmod +x test-token.sh
./test-token.sh YOUR_TOKEN_HERE
```
**Expected Output:**
```bash
🔍 Testing token: eyJhbGciOiJIUzI1NiI...
✅ Token is VALID!
Projects: {"list":[...]}
🎉 Your token is working correctly!
```
### **✅ MCP Server Testing:**
```bash
# Test MCP server endpoint
curl https://mcp-nocodb.v1su4.com/
# Test health check via MCP
curl -X POST https://mcp-nocodb.v1su4.com/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"health_check","arguments":{}},"id":1}'
# Test NocoDB connection via MCP
curl -X POST https://mcp-nocodb.v1su4.com/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"nocodb_test_connection","arguments":{}},"id":1}'
```
---
## 🚨 Common Issues & Solutions
### **Issue 1: 401 Unauthorized**
**Symptoms:** `{"error":"AUTHENTICATION_REQUIRED","message":"Authentication required - Invalid token"}`
**Solutions:**
1. ✅ **Check header name**: Use `xc-token`, not `xc-auth`
2. ✅ **Verify token format**: Should be JWT-like string starting with `eyJ`
3. ✅ **Test token directly**: Use the validation script above
4. ✅ **Check token expiration**: Generate new token if expired
### **Issue 2: SSL Certificate Errors**
**Symptoms:** `curl: (60) SSL certificate problem`
**Solutions:**
1. ✅ **Use `-k` flag**: `curl -k` to bypass SSL verification during development
2. ✅ **Check SSL certificate**: Ensure Let's Encrypt is properly configured
3. ✅ **Update curl**: `curl --version` should show recent version
### **Issue 3: Connection Refused**
**Symptoms:** `Failed to connect to nocodb.v1su4.com port 443`
**Solutions:**
1. ✅ **Check server status**: Ensure NocoDB instance is running
2. ✅ **Verify URL**: Confirm `https://nocodb.v1su4.com` is accessible
3. ✅ **Check firewall**: Ensure port 443 is open
4. ✅ **DNS resolution**: `nslookup nocodb.v1su4.com`
---
## 📊 Available MCP Tools
### **Connection & Management:**
- `nocodb_test_connection` - Verify database connectivity
- `nocodb_list_projects` - Browse available projects
- `nocodb_list_tables` - View tables in a project
### **Data Operations:**
- `nocodb_get_records` - Retrieve records with pagination
- `nocodb_create_record` - Add new records
- `nocodb_update_record` - Modify existing records
- `nocodb_delete_record` - Remove records
- `nocodb_search_records` - Search with filters
### **Specialized:**
- `nocodb_create_discord_reactions_table` - Create Discord reactions table
- `nocodb_get_analytics` - Get Discord reactions analytics
---
## 🏗️ Deployment Architecture
### **Production Setup (Coolify):**
```yaml
# docker-compose.yaml (for local testing)
services:
mcp-server-nocodb:
image: gordov1su4/mcp-server-nocodb:1.2.0
container_name: mcp-server-nocodb
restart: unless-stopped
environment:
- PORT=3001
- NOCODB_URL=https://nocodb.v1su4.com
- NOCODB_API_TOKEN=${NOCODB_API_TOKEN}
- PYTHONUNBUFFERED=1
ports:
- "3001:3001"
```
### **Development Setup:**
```bash
# Local testing with docker-compose
docker-compose up -d
# View logs
docker-compose logs -f mcp-server-nocodb
# Or run directly
python nocodb_mcp_server.py
```
---
## 🔒 Security Best Practices
### **1. API Key Management:**
- ✅ **Store securely**: Never commit to GitHub
- ✅ **Use environment variables**: No hardcoded values
- ✅ **Rotate regularly**: Change tokens every 3-6 months
- ✅ **Different keys**: Separate MCP and NocoDB tokens
### **2. Network Security:**
- ✅ **HTTPS only**: Enforce SSL/TLS encryption
- ✅ **Rate limiting**: Implement request limits
- ✅ **Input validation**: Sanitize all user inputs
- ✅ **Logging**: Monitor all API requests
### **3. Authentication:**
- ✅ **Bearer tokens**: Use JWT for MCP server auth
- ✅ **xc-token header**: Use correct NocoDB API format
- ✅ **Token validation**: Verify tokens on every request
- ✅ **Expiration handling**: Implement token refresh logic
---
## 📚 API Reference
### **NocoDB API v3 Endpoints (Primary):**
```bash
# Bases (Projects in v3)
GET /api/v3/meta/bases
# Tables
GET /api/v3/meta/bases/{base_id}/tables
POST /api/v3/meta/bases/{base_id}/tables
# Records (Note: base_id required in v3)
GET /api/v3/data/{base_id}/{table_id}/records
POST /api/v3/data/{base_id}/{table_id}/records
GET /api/v3/data/{base_id}/{table_id}/records/{recordId}
PATCH /api/v3/data/{base_id}/{table_id}/records?recordId={recordId}
DELETE /api/v3/data/{base_id}/{table_id}/records?recordId={recordId}
GET /api/v3/data/{base_id}/{table_id}/count
```
**Note**: This server uses **API v3 as primary** (NocoDB 0.264.0+). Latest stable: 0.265.1. Automatic v2 fallback for compatibility. API v3 provides embedded relations, unified linking, and standardized responses. See [API v3 release notes](https://github.com/nocodb/nocodb/releases/tag/0.264.0) and [latest release](https://github.com/nocodb/nocodb/releases/tag/0.265.1).
### **MCP Server Endpoints:**
```bash
# MCP protocol endpoint (uses JSON-RPC 2.0 over HTTP/SSE)
POST / (MCP streamable-http transport)
# All MCP operations go through the root endpoint
# Uses standard MCP protocol methods:
# - initialize
# - tools/list
# - tools/call
```
---
## 🎯 Use Cases
### **Discord Heart Reactions Workflow:**
```json
{
"name": "nocodb_create_record",
"arguments": {
"project_id": "pce7ccvwdlz09bx",
"table_id": "your_table_id",
"record_data": {
"message_content": "Discord message content",
"discord_message_id": "msg_123",
"discord_channel_id": "channel_456",
"timestamp": "2024-01-01T00:00:00Z"
}
}
}
```
### **Analytics Query:**
```json
{
"name": "nocodb_get_analytics",
"arguments": {
"project_id": "pce7ccvwdlz09bx",
"table_id": "your_table_id"
}
}
```
---
## 🚀 Quick Start
1. **Generate NocoDB token**: `nocodb.v1su4.com` → Account Settings → Tokens
2. **Test token**: `./test-nocodb-token.sh YOUR_TOKEN`
3. **Set environment variables**: `MCP_API_KEY` and `NOCODB_API_TOKEN`
4. **Update Cursor config**: Add MCP server configuration
5. **Test connection**: Use MCP tools in Cursor
---
## 📞 Support
**For NocoDB API issues:**
- Check: `nocodb.v1su4.com/api/v2/meta/bases/pce7ccvwdlz09bx/swagger`
- Use: `xc-token` header (not `xc-auth`)
- Test with: `./test-nocodb-token.sh`
**For MCP server issues:**
- Health: Test via MCP `health_check` tool
- Connection: `curl https://mcp-nocodb.v1su4.com/`
- Logs: Check Coolify service logs
- See: [MCP_SERVER_TROUBLESHOOTING.md](MCP_SERVER_TROUBLESHOOTING.md) for detailed troubleshooting
**This setup is optimized for home-ran NocoDB instances and provides robust API integration with Cursor IDE!** 🎉
