# Claude.ai Integration Guide
**⚠️ IMPORTANT: External Service Notice**
This guide covers integration with Claude.ai, an external third-party service. Before proceeding with this integration:
- Ensure Claude.ai is an approved vendor per FastMCP's procurement policies
- Review and comply with all FastMCP security and data governance requirements
- Contact your FastMCP security team for approval before connecting to external services
## Overview
This guide explains how to configure your MCP server to work with Claude.ai as a remote MCP server.
## Requirements for Claude.ai Integration
Based on Claude.ai's MCP documentation:
### 1. HTTPS and Domain Requirements
- **Real SSL Certificate**: Claude.ai requires a publicly trusted SSL certificate
- **Public Domain**: Your server must be accessible from the internet
- **OAuth Callback URL**: Must match `https://claude.ai/api/mcp/auth_callback`
### 2. Supported Features
- ✅ OAuth-based authentication with Dynamic Client Registration (DCR)
- ✅ SSE and Streamable HTTP transport
- ✅ Tools, prompts, and resources
- ✅ Token expiry and refresh
## Deployment Options
### Option 1: Cloudflare Workers (Recommended)
Cloudflare provides built-in MCP server hosting with OAuth management:
```bash
# Install Cloudflare CLI
npm install -g wrangler
# Deploy your MCP server
wrangler deploy
```
### Option 2: ngrok Tunnel (Development/Testing)
**Note**: Ensure tunneling services like ngrok are approved for use within FastMCP's network security policies.
Expose your localhost server with HTTPS:
```bash
# Install ngrok (requires approval for external tools)
brew install ngrok
# Create a tunnel with custom domain (requires ngrok account)
ngrok http 8002 --domain=your-app.ngrok-free.app
# Your server will be available at:
# https://your-app.ngrok-free.app
```
### Option 3: Cloud Deployment
**Note**: All cloud deployments must use FastMCP-approved infrastructure and comply with data governance policies.
Deploy to any cloud service with HTTPS:
- **Railway**: Automatic HTTPS with custom domains (requires approval)
- **Render**: Free tier with HTTPS (requires approval)
- **Heroku**: Built-in HTTPS support (requires approval)
- **DigitalOcean App Platform**: Managed HTTPS (requires approval)
- **AWS/GCP/Azure**: With load balancer and certificates (use FastMCP-approved accounts)
## Configuration for Claude.ai
### 1. Update Environment Variables
Create a production `.env` file:
```env
# Production Configuration
ENVIRONMENT=production
DEBUG=false
# Server Configuration
HOST=0.0.0.0
PORT=8002
SERVER_NAME=your-domain.com
# HTTPS Configuration (for cloud deployment)
USE_HTTPS=true
SSL_CERT_PATH="" # Let cloud provider handle certificates
SSL_KEY_PATH=""
# OAuth Configuration for Claude.ai
OAUTH_BASE_URL=https://your-app.FastMCP.internal
OAUTH_CLIENT_NAME=Claude
OAUTH_ALLOWED_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
# Google OAuth Configuration
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_PROJECT_ID=your-project-id
# Phase 1 Feature Flags
PHASE1_ENABLE_FASTMCP_PROVIDER=true
PHASE1_DUAL_FLOW_MODE=true
PHASE1_FASTMCP_PRIMARY=false
```
### 2. Update Google OAuth Configuration
In your Google Cloud Console:
1. Add Claude.ai callback URLs to authorized redirect URIs:
- `https://claude.ai/api/mcp/auth_callback`
- `https://claude.com/api/mcp/auth_callback`
2. Add your production domain to authorized JavaScript origins:
- `https://your-app.FastMCP.internal`
### 3. Configure OAuth Endpoints
Update `auth/fastmcp_oauth_endpoints.py` for Claude.ai compatibility:
```python
# Ensure OAuth discovery endpoints return production URLs
OAUTH_BASE_URL = settings.oauth_base_url or f"https://{settings.server_name}"
MCP_RESOURCE_URL = f"{OAUTH_BASE_URL}/mcp"
```
## Local Development Setup
For local development and testing:
### 1. Create Development Certificates
```bash
# Create localhost certificates with mkcert
mkcert localhost 127.0.0.1 ::1
```
### 2. Local Environment Configuration
```env
# Development Configuration
ENVIRONMENT=development
DEBUG=true
# Server Configuration
HOST=localhost
PORT=8002
SERVER_NAME=localhost
# HTTPS Configuration (local)
USE_HTTPS=true
SSL_CERT_PATH=./localhost+2.pem
SSL_KEY_PATH=./localhost+2-key.pem
# OAuth Configuration (local testing)
OAUTH_BASE_URL=https://localhost:8002
```
## Testing Your Server
### 1. Local Testing
1. Start your server: `python server.py`
2. Test with MCP Inspector: `npx @modelcontextprotocol/inspector https://localhost:8002/mcp`
3. Verify OAuth flow works
### 2. Claude.ai Testing
1. Deploy your server to a public domain with HTTPS
2. In Claude.ai, go to Settings > Connectors
3. Add your server URL: `https://your-app.FastMCP.internal/mcp`
4. Complete OAuth authentication flow
5. Test MCP tools and resources
## Security Considerations
### IP Whitelisting (Optional)
If you want to restrict access to Claude.ai only, whitelist these IP addresses:
- Check Claude.ai documentation for current IP ranges
- Configure your firewall/load balancer accordingly
### OAuth Security
- Use strong, unique client secrets
- Enable token refresh for better security
- Monitor OAuth logs for unauthorized access attempts
## Troubleshooting
### Common Issues
1. **Certificate Errors**
- Ensure your domain has a valid SSL certificate
- Check certificate expiration dates
- Verify certificate chain is complete
2. **OAuth Flow Issues**
- Verify redirect URIs match exactly
- Check client ID and secret configuration
- Ensure Dynamic Client Registration is working
3. **Connection Timeouts**
- Verify server is publicly accessible
- Check firewall rules
- Ensure server is running on correct port
### Debug Endpoints
Your server exposes these debug endpoints:
- `GET /health` - Server health check
- `GET /oauth/discovery` - OAuth configuration
- `GET /mcp` - MCP server endpoint
## Migration from Local to Production
1. **Update DNS**: Point your domain to your server
2. **Configure HTTPS**: Set up SSL certificates
3. **Update OAuth**: Add production redirect URIs
4. **Environment Variables**: Switch to production config
5. **Test**: Verify all functionality works
6. **Claude.ai**: Add your server in Claude.ai settings
## Support
For issues:
1. Check server logs for detailed error messages
2. Test with MCP Inspector first
3. Verify OAuth flow with curl/Postman
4. Check Claude.ai connector status in settings
