# Handoff: MCP Server Deployment

## Context
Auth0 integration is complete. The MCP server is ready for deployment to a dedicated server. The next agent will handle the deployment ticket.

## Quick Reference for Next Agent

### Server Status
- **Framework**: Official MCP Python SDK (migrated from FastMCP)
- **Auth**: Auth0 DCR enabled, Resource Server created, domain-level connection promoted
- **Transport**: HTTP (StreamableHTTP) via FastAPI + Uvicorn
- **JWT Validation**: Auth0TokenVerifier class using JWKS endpoint
- **Local Server**: server_local.py unchanged (continues to work for development)

### Auth0 Configuration (Production - Already Done)
- **Tenant**: point-topic.eu.auth0.com
- **DCR**: Enabled ✓
- **Resource Server**: Point Topic MCP (ID: 69845884cff12c8feb369c46)
- **Connection**: Username-Password-Authentication promoted to domain level ✓
- **Universal Login**: Shows Point Topic branding directly (no proxy)

### Key Files
- `src/point_topic_mcp/server_http.py` - Main server (official MCP SDK)
- `src/point_topic_mcp/auth/auth0_helpers.py` - JWT validation
- `pyproject.toml` - Dependencies (mcp>=1.26.0, fastapi, uvicorn, pyjwt)
- `infrastructure/auth0-cheat-sheet.sh` - Auth0 CLI reference
- `infrastructure/auth0-credentials.json` - Credentials (gitignored, 600 perms)

### Environment Variables Needed
```bash
AUTH0_DOMAIN=point-topic.eu.auth0.com
AUTH0_AUDIENCE=https://point-topic-mcp.fastmcp.app/
MCP_SERVER_URL=https://point-topic-mcp.fastmcp.app
MCP_HTTP_PORT=8000
```

### Useful Documentation Links

**MCP Specification:**
- https://modelcontextprotocol.io/specification/draft/basic/authorization
- RFC 9728: OAuth 2.0 Protected Resource Metadata

**Working Examples:**
- https://github.com/CefBoud/mcp-simple-auth0 (Official SDK + Auth0 DCR pattern)
- https://github.com/modelcontextprotocol/python-sdk (official SDK docs)

**Deployment References:**
- Google Cloud Run MCP hosting: https://cloud.google.com/run/docs/host-mcp-servers
- Solo.io MCP auth blog: https://www.solo.io/blog/part-two-mcp-authorization-the-hard-way
- MCP Auth spec guide: https://www.mcpjam.com/blog/mcp-oauth-guide

**Auth0 DCR:**
- https://auth0.com/docs/get-started/applications/dynamic-client-registration
- Apollo MCP + Auth0: https://www.apollographql.com/docs/apollo-mcp-server/guides/auth-auth0

### Testing OAuth Flow
```bash
# After deployment, test with:
curl https://your-server/.well-known/oauth-protected-resource
# Should return Auth0 authorization server URL

# Client should then:
# 1. Get 401 from /mcp endpoint
# 2. Fetch metadata
# 3. Open Auth0 login directly
# 4. Authenticate and get JWT
# 5. Call /mcp with Bearer token
```

### Common Issues & Solutions

**Issue**: Auth0 Universal Login not showing
**Solution**: Check DCR is enabled: `auth0 api get tenants/settings | grep enable_dynamic_client_registration`

**Issue**: JWT validation fails
**Solution**: Verify audience matches resource server identifier exactly (trailing slash matters!)

**Issue**: Connection not available for third-party clients
**Solution**: Check connection is domain-level: `auth0 api get connections/{id} | grep is_domain_connection`

### Contacts/Resources
- **Peter Donaghey** (user) - Point Topic Admin, has full Auth0 access
- **Auth0 CLI**: `auth0 login` → manage tenant settings
- **Management API**: https://auth0.com/docs/api/management/v2
- **GitHub Repo**: Point-Topic/point-topic-mcp (agent-dev branch)

### Notes
- server_local.py intentionally unchanged - local development continues without auth
- All Auth0 config is production tenant (point-topic.eu.auth0.com)
- The migration from FastMCP to official SDK is complete
- Server uses FastAPI with official MCP SDK, not FastMCP

---
**Next Steps**: Deploy to dedicated server, configure SSL, test OAuth flow with Cursor/Claude
