MCP troubleshooting

# Example: Check token claims
curl -X GET https://your-mcp-server.com/api/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

# If 401, inspect token at jwt.io:
# - exp: 1735689600 (must be in future)
# - aud: "https://your-mcp-server.com" (must match server URI)
# - scope: "read:application" (must include required scopes)

### CORS Errors in Browser

**Symptom**: Browser console shows CORS errors when MCP client attempts to connect to Hanzo IAM.

**Causes**:

- Hanzo IAM CORS settings don't include the MCP client's origin
- Preflight requests are being blocked
- Wildcard CORS is disabled for security

**Fix**:

1. Log into Hanzo IAM admin panel
2. Navigate to your application configuration
3. Add the MCP client's origin to the **CORS Allowed Origins** field
4. Include the full origin: `https://client-domain.com` (with scheme and port if non-standard)
5. For local development, add `http://localhost:PORT`

```text
# Example CORS configuration:
https://claude.ai
https://cursor.sh
http://localhost:3000

### Redirect URI Mismatch

**Symptom**: OAuth flow fails with `redirect_uri_mismatch` error.

**Causes**:

- The `redirect_uri` in the authorization request doesn't exactly match the application configuration
- Scheme mismatch (`http` vs `https`)
- Port number missing or incorrect
- Trailing slash mismatch

**Fix**:

1. Copy the exact `redirect_uri` from your authorization request
2. In Hanzo IAM, edit the application configuration
3. Add the exact URI to **Redirect URLs** field (must match character-for-character)
4. Ensure scheme, host, port, and path all match exactly

```bash
# These are all different redirect URIs:
http://localhost:3000/callback
https://localhost:3000/callback  # Different scheme
http://localhost:3000/callback/  # Trailing slash
http://localhost:3001/callback   # Different port

### Discovery Endpoint 404

**Symptom**: Attempting to fetch `.well-known` discovery document returns 404.

**Causes**:

- Using wrong discovery path for your use case
- Hanzo IAM configuration doesn't expose discovery endpoints
- Application not configured as OIDC provider

**Fix**:

Try these discovery endpoints in order:

1. **OAuth Authorization Server Metadata** (RFC 8414):

   ```bash
   curl https://your-iam.com/.well-known/oauth-authorization-server

npx @modelcontextprotocol/inspector

Features:

- Interactive tool browser and testing
- Real-time JSON-RPC request/response viewer
- OAuth flow testing
- Connection diagnostics

### Testing Discovery Endpoints

Verify each discovery endpoint returns valid JSON:

```bash
# OAuth Authorization Server
curl -s https://your-iam.com/.well-known/oauth-authorization-server | jq

# OIDC Configuration
curl -s https://your-iam.com/.well-known/openid-configuration | jq

# Protected Resource (for MCP resource servers)
curl -s https://your-mcp-server.com/.well-known/oauth-protected-resource | jq

### Inspecting JWT Tokens

Use [jwt.io](https://jwt.io) to decode access tokens and verify claims:

**Key claims to check**:

- `aud` (audience): Must match MCP server URI
- `scope`: Must include required scopes for tools
- `exp` (expiration): Must be in the future (Unix timestamp)
- `iss` (issuer): Should match Hanzo IAM's authorization server URL
- `sub` (subject): User identifier
- `client_id`: Application/client that received the token

```bash
# Alternative: Decode token with jq
echo "YOUR_JWT_TOKEN" | cut -d. -f2 | base64 -d | jq

### Token Introspection Endpoint

Hanzo IAM provides a token introspection endpoint (RFC 7662) to validate and inspect tokens:

```bash
curl -X POST https://your-iam.com/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "token=ACCESS_TOKEN"

Response includes:

```json
{
  "active": true,
  "scope": "read:application write:application",
  "client_id": "your-client-id",
  "username": "admin",
  "exp": 1735689600,
  "iat": 1735603200,
  "aud": "https://your-mcp-server.com"
}

### Testing with curl

Manual OAuth flow testing with curl:

```bash
# 1. Test authorization endpoint (requires browser)
# Open in browser:
https://your-iam.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=http://localhost:8080/callback&
  response_type=code&
  scope=read:application&
  state=random-state

# 2. Exchange authorization code for token
curl -X POST https://your-iam.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=http://localhost:8080/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# 3. Use access token with MCP server
curl https://your-mcp-server.com/api/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

### Debug Logging

Enable debug logging in your MCP client or server to see detailed OAuth flows:

**For MCP clients**:

- Check client configuration for debug/verbose mode
- Review client logs for OAuth redirect, token exchange, and API calls
- Capture network traffic with browser DevTools or mitmproxy

**For MCP servers**:

- Enable server debug logging to see incoming requests
- Log token validation results (success/failure and reasons)
- Monitor authorization checks and scope validation

### Network Debugging

Use browser DevTools or network analysis tools:

1. **Browser DevTools (F12)**:
   - Network tab shows all OAuth redirects and API calls
   - Console tab displays JavaScript errors
   - Application tab shows stored tokens and cookies

2. **mitmproxy** for CLI clients:

   ```bash
   mitmproxy -p 8080
   # Configure client to use proxy: http://localhost:8080