HeyClaude MCP Server

OAuth authentication failed or token audience mismatch

Verify OAuth 2.1 flow completed correctly (authorization code with PKCE). Check token audience claim includes MCP server URL (https://mcp.heyclau.de/mcp). Ensure resource parameter (RFC 8707) was included in authorization request. Verify redirect URI matches registered URI in Supabase Auth. Check token not expired (refresh if needed). Review OAuth metadata endpoints: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Ensure JWT token includes correct audience in 'aud' claim. Re-authenticate if token was issued without resource parameter.

JWT token validation errors or missing audience claim

OAuth 2.1 requires resource parameter (RFC 8707) to include MCP server URL in token audience. Verify token was issued with resource parameter in authorization request. Check token 'aud' claim includes https://mcp.heyclau.de/mcp. Re-authenticate if token was issued without resource parameter. Review authorization endpoint: /oauth/authorize (proxies to Supabase Auth with resource parameter). Ensure client uses OAuth 2.1 flow, not OAuth 2.0. Check token expiration and refresh if needed. Verify client ID and redirect URI are correct in Supabase Auth configuration.

Tool execution errors or database query failures

Check Row-Level Security (RLS) policies allow access for authenticated user. Verify Supabase client authenticated correctly (token in Authorization header). Review tool pagination limits (max 50 items per request, some tools max 20). Check database connection and RPC availability. Review error messages in tool responses for specific issues. Verify category and slug parameters are correct (valid categories: agents, rules, commands, skills, collections, mcp). Check content exists in directory for specified category/slug. Review tool input schema requirements (required vs optional parameters).

Connection errors or endpoint unreachable

Verify network access to mcp.heyclau.de (HTTPS required). Check endpoint URL correct: https://mcp.heyclau.de/mcp (primary), https://mcp.claudepro.directory/mcp (legacy), or direct Supabase endpoint. Test health endpoint: https://mcp.heyclau.de/ (should return server info with version 1.0.0, protocol 2025-06-18). Verify CORS headers allow requests from your client. Check MCP Protocol Version header matches 2025-06-18. Review Mcp-Session-Id header if using session management. Verify HTTP transport (not STDIO) for remote server. Check firewall or network restrictions blocking HTTPS connections.