# 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:**
```bash
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:

```bash
# 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`:
```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](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)
- [OAuth 2.1 Draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1)
- [Dynamic Client Registration RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)

## 🐛 **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.