Airtable MCP Server

A production-ready MCP server that implements the complete OAuth 2.1 specification with Dynamic Client Registration, designed specifically for Claude's connector requirements.

🔐 OAuth 2.1 Compliance

This server implements the full MCP Authorization specification:

• ✅ Dynamic Client Registration (RFC 7591) - Required by Claude
• ✅ OAuth 2.1 with PKCE - Secure authorization flow
• ✅ Authorization Server Metadata (RFC 8414) - Auto-discovery
• ✅ Protected Resource Metadata (RFC 9728) - Resource discovery
• ✅ Bearer Token Authentication - Secure API access

🚀 Quick Deploy to Railway

1. Commit and push your changes:

git add .
git commit -m "Implement proper OAuth 2.1 MCP server with Dynamic Client Registration"
git push origin main

2. Railway will auto-deploy - just ensure these environment variables are set:

   • AIRTABLE_API_KEY = your Airtable API token

3. Configure Claude:

   • Copy your Railway URL (e.g., https://airtable-mcp-server-production-6389.up.railway.app)
   • In Claude connector setup, use this URL
   • Leave OAuth Client ID empty - Dynamic Client Registration handles this automatically

🔧 Environment Variables

Required:

• AIRTABLE_API_KEY - Your Airtable API token

Optional (Railway sets automatically):

• BASE_URL - Your deployed URL
• PORT - Server port (default: 8000)
• HOST - Server host (default: 0.0.0.0)

🧪 Testing Your Server

After deployment, test the OAuth endpoints:

# Test Dynamic Client Registration
curl -X POST https://your-app.railway.app/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Test Client", "redirect_uris": ["https://example.com/callback"]}'

# Check OAuth metadata
curl https://your-app.railway.app/.well-known/oauth-authorization-server

# Setup information
curl https://your-app.railway.app/setup

📋 MCP Tools Available

• list_bases - List all accessible Airtable bases
• list_tables - List tables in a specific base
• list_records - Get records from a table with filtering
• create_record - Create new records in tables

🔗 Claude Integration

For Claude Web Interface:

1. Go to Settings → Connectors
2. Add custom connector with your Railway URL
3. Leave OAuth Client ID empty (Dynamic Client Registration is used)
4. Claude will automatically register and authenticate

For Claude Desktop: Use the MCP connector configuration in claude_desktop_config.json:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-client"],
      "env": {
        "MCP_SERVER_URL": "https://your-app.railway.app"
      }
    }
  }
}

🏗️ Architecture

This server separates concerns properly:

• Authorization Server - Handles OAuth 2.1 flows
• Resource Server - Protects MCP endpoints
• Dynamic Client Registration - Auto-registers Claude clients
• Airtable Client - Secure API integration

🔒 Security Features

• PKCE (RFC 7636) - Prevents authorization code interception
• Secure token storage - Tokens expire and rotate
• Input validation - All endpoints validate requests
• HTTPS enforcement - All OAuth endpoints require HTTPS
• Scope-based access - Granular permission control

📚 MCP Specification Compliance

Built according to the official MCP specification:

• MCP Authorization Spec
• OAuth 2.1 Draft
• Dynamic Client Registration RFC 7591

🐛 Troubleshooting

Claude connector fails to add:

1. Ensure your Railway app is deployed and accessible
2. Check that AIRTABLE_API_KEY is set in Railway environment
3. Verify the URL returns {"status": "healthy"} at /health
4. Check Railway logs for any startup errors

OAuth flow issues:

1. Test Dynamic Client Registration endpoint manually
2. Verify OAuth metadata endpoints are accessible
3. Check that BASE_URL environment variable matches your actual Railway URL

🎯 What's Different Now

This implementation fixes the previous issues:

❌ Before:

• Simple API key authentication (rejected by Claude)
• No Dynamic Client Registration support
• Missing OAuth metadata endpoints
• No PKCE security

✅ Now:

• Full OAuth 2.1 compliance with Dynamic Client Registration
• Auto-discovery endpoints for Claude to find OAuth servers
• PKCE security for public clients like Claude
• Proper MCP authorization flow following the specification

📄 License

MIT License - feel free to use this as a template for your own MCP servers.