Troubleshooting Guide

Common issues and solutions for Seed MCP Server users and administrators.

For Users

Problems connecting to or using Seed from your MCP client.

Connection Issues

"Cannot connect to MCP server"

Symptoms:

Client shows connection error
Tools/prompts not available
Timeout errors

Solutions:

Verify server URL - Check with your administrator
- Should include /mcp path (e.g., https://mcp.example.com/mcp)
- Test in browser: https://YOUR_SERVER_URL/health
Check network connectivity
- Can you reach other sites?
- Are you on VPN if required?
- Check firewall rules
Verify server is running - Contact your administrator
Check client configuration - Ensure JSON syntax is correct

"OAuth authentication failed"

Symptoms:

Browser doesn't open for login
Login page doesn't load
"Authentication failed" error

Solutions:

Verify OAuth endpoints - Check authorizationUrl and tokenUrl with admin
Test OAuth URLs in browser - Should be accessible
Clear browser cookies - For the OAuth domain
Try incognito/private mode - Rules out browser extensions
Check redirect URI - Must match server configuration
Verify account access - Confirm with administrator you have permissions

"Token expired" or "Unauthorized"

Symptoms:

Worked before, now getting 401 errors
"Token expired" message

Solutions:

Re-authenticate - Client will prompt you to log in again (normal after extended inactivity)
Check session - May have been cleared on server
Verify account status - Confirm access wasn't revoked

"Invalid configuration" or "Invalid settings.json"

Symptoms:

Client won't start
Configuration error messages

Solutions:

Validate JSON syntax
- Check for missing commas
- Check for missing quotes
- Use a JSON validator
Verify required fields - url, transport, authentication type
Check URLs - Must be valid HTTPS URLs (or HTTP for localhost)
Reload client - Restart after fixing configuration

Tool/Prompt Issues

"Tool not found" or "Prompt not available"

Symptoms:

Specific tool/prompt doesn't appear
"Tool not found" errors

Solutions:

Verify tool is enabled - Administrator controls available tools
Check authentication - Some tools require authenticated access
Refresh connection - Disconnect and reconnect
Check server version - Tool may not be available in your server version

"Tool execution failed"

Symptoms:

Tool starts but returns an error
Partial results

Solutions:

Check parameters - Ensure correct argument types and values
Verify permissions - You may not have access to that specific action
Check server logs - Ask administrator to review for errors
Try different tool - Isolate if it's tool-specific or general issue

Performance Issues

"Slow response times"

Symptoms:

Tools take a long time to respond
Timeouts

Solutions:

Check network - Test connection speed
Increase timeout - Configure longer timeout in client settings
Contact administrator - Server may be under high load
Use different tool - Some operations naturally take longer

"Frequent disconnections"

Symptoms:

Connection drops repeatedly
Need to re-authenticate often

Solutions:

Check network stability - WiFi issues, VPN drops
Verify firewall - May be closing idle connections
Contact administrator - Session timeout settings may need adjustment

Client-Specific Issues

Claude Desktop

"MCP servers not loading"

Restart Claude Desktop completely (not just close window)
Check configuration file location is correct
Validate JSON in configuration file

"Settings not saving"

Ensure you have write permissions to config directory
Check disk space
Try editing config file directly

Claude Code (VSCode)

"Extension not detecting MCP servers"

Reload VSCode window: Cmd+Shift+P → "Reload Window"
Check extension is up to date
Verify settings.json location (user vs workspace)
Check VSCode developer console for errors: Help → Toggle Developer Tools

"OAuth callback not working"

Check default browser is set correctly
Try different browser
Verify localhost ports aren't blocked

GitHub Copilot

"MCP not available"

Ensure VS Code 1.102+ or latest JetBrains version
Update GitHub Copilot extension
Check MCP support in your IDE version

Microsoft Copilot

"Cannot add MCP server"

Verify Copilot Studio access level
Ensure generative orchestration is enabled
Check tenant MCP policies with administrator

For Administrators

Server setup, configuration, and operational issues.

Startup Issues

"Server won't start"

Check logs:

bash

docker logs seed-mcp-server
# or
npm run dev  # See console output

Common causes:

Missing environment variables - Check required vars are set
Port already in use - Another process using port 3000
Redis connection failed - Verify Redis is running and accessible
Invalid OIDC configuration - Check issuer URL, JWKS URL

Solutions:

bash

# Check if port is in use
lsof -i :3000

# Test Redis connection
redis-cli ping

# Validate environment variables
env | grep OIDC
env | grep REDIS

"JWKS discovery failed"

Symptoms:

"Cannot fetch JWKS" errors
"Invalid issuer" errors

Solutions:

Verify OIDC_ISSUER - Should be your identity provider's base URL

Test OpenID configuration endpoint:

bash

curl https://YOUR_ISSUER/.well-known/openid-configuration

Check JWKS URL - Should return public keys:
bash
```
curl https://YOUR_ISSUER/.well-known/jwks
```
1
Check firewall - Server must reach identity provider
Use explicit OIDC_JWKS_URL - If autodiscovery doesn't work

Authentication Issues

"All requests return 401 Unauthorized"

Check configuration:

bash

# Verify auth is enabled (should be true for production)
echo $AUTH_REQUIRED

# Check OIDC configuration
echo $OIDC_ISSUER
echo $OIDC_AUDIENCE
echo $OIDC_JWKS_URL

Solutions:

Verify JWT tokens - Use jwt.io to decode and inspect
Check issuer claim - Must match OIDC_ISSUER
Check audience claim - Must match OIDC_AUDIENCE
Verify token signature - Check against JWKS public keys
Check token expiration - May be using expired tokens

"OAuth flow fails"

Check OAuth configuration:

bash

echo $OAUTH_AUTHORIZATION_URL
echo $OAUTH_TOKEN_URL

Test OAuth endpoints:

bash

# Should return OAuth metadata
curl https://YOUR_SERVER/oauth/token

# Should redirect to authorization page
curl -I https://YOUR_SERVER/oauth/authorize?client_id=test

Common issues:

Client not registered - Use dynamic client registration or pre-register
Redirect URI mismatch - Must exactly match registered URI
Invalid client_id - Check client registration
PKCE validation failed - Ensure code_verifier matches code_challenge

Redis Issues

"Session not found" errors

Check Redis connection:

bash

redis-cli ping
redis-cli KEYS "seed:*"

Solutions:

Verify REDIS_URL - Format: redis://host:port
Check Redis is running - redis-cli ping should return "PONG"
Check network - Server can reach Redis host
Verify credentials - If Redis has authentication
Check TTL settings - Sessions may be expiring too quickly

"Redis connection refused"

Solutions:

bash

# Check Redis is running
systemctl status redis
# or
docker ps | grep redis

# Test connection
redis-cli -h YOUR_REDIS_HOST -p YOUR_REDIS_PORT ping

# Check firewall rules
telnet YOUR_REDIS_HOST YOUR_REDIS_PORT

Performance Issues

"High memory usage"

Check:

bash

# Check Redis memory
redis-cli INFO memory

# Check Node process memory
ps aux | grep node

Solutions:

Adjust Redis memory limits - Set maxmemory in redis.conf
Clean up old sessions - Ensure TTL is set correctly
Enable Redis eviction - maxmemory-policy in redis.conf
Scale Redis - Use Redis Cluster for large deployments

"Slow API responses"

Diagnose:

Check logs - Look for slow operations
Monitor Redis latency - redis-cli --latency
Check JWKS cache - Frequent JWKS fetches indicate issues
Network latency - Test latency to identity provider

Solutions:

Increase JWKS cache TTL - Reduce OIDC provider calls
Use Redis connection pooling - If not already enabled
Scale horizontally - Deploy multiple Seed instances behind load balancer
Optimize Redis - Use appropriate data structures, enable pipelining

Security Issues

"Suspicious authentication attempts"

Monitor logs for:

Repeated 401 errors from same IP
Invalid JWT tokens
OAuth abuse attempts

Actions:

Enable rate limiting - Limit requests per IP
Review IP allowlists - Block suspicious IPs at firewall level
Audit user access - Review who has tokens issued
Rotate signing keys - At identity provider

"Token leakage suspected"

Immediate actions:

Revoke compromised tokens - At identity provider
Rotate client secrets - For affected clients
Review access logs - Identify unauthorized usage
Force re-authentication - Clear all sessions

Prevention:

Use short token lifetimes - 1 hour or less
Enable token rotation - Refresh tokens regularly
Implement token binding - Bind tokens to specific clients
Monitor unusual patterns - Geographic, temporal anomalies

Monitoring & Health Checks

Health Check Endpoint

Test server health:

bash

curl https://YOUR_SERVER/health

Expected response:

json

{
  "status": "ok",
  "timestamp": "2025-01-05T12:00:00.000Z",
  "uptime": 3600.5,
  "redis": {
    "connected": true,
    "ping": "PONG"
  }
}

Monitoring Recommendations

Key metrics to track:

Response time - 95th percentile latency
Error rate - 4xx/5xx responses per minute
Active connections - Current MCP sessions
Redis memory - Usage and hit rate
JWT validation time - JWKS fetch latency
OAuth success rate - Authorization flow completions

Alerting thresholds:

Response time > 2s (95th percentile)
Error rate > 5%
Redis memory > 80%
JWKS fetch failures > 1%

Logging & Debugging

Enable Debug Logging

Production:

bash

LOG_LEVEL=debug npm start

Development:

bash

DEBUG=* npm run dev

Log Locations

Docker:

bash

docker logs -f seed-mcp-server
docker logs --tail 100 seed-mcp-server

System:

bash

journalctl -u seed-mcp-server -f
tail -f /var/log/seed/*.log

Key Log Events

Watch for:

JWT verification failed - Authentication issues
JWKS fetch error - Identity provider connectivity
Redis connection error - Session store issues
MCP session created - New client connections
OAuth token exchange - Authorization flow steps

Getting Additional Help

For Users

Contact your administrator - Server configuration and access issues
Check server status - https://YOUR_SERVER/health
Review documentation - Connection guides, Tools, Prompts, Resources

For Administrators

Review architecture docs - Authentication Flow, OAuth Implementation, Session Management
Check API reference - MCP Endpoints, OAuth Endpoints
Developer guide - Installation, Configuration, Deployment
Report issues - GitHub issues or internal support channels

Common Error Codes

Code	Meaning	Action
401	Unauthorized	Check authentication, verify token
403	Forbidden	Check permissions, verify access grants
404	Not Found	Verify URL path, check resource exists
429	Too Many Requests	Reduce request rate, wait and retry
500	Internal Server Error	Check server logs, contact administrator
502	Bad Gateway	Check upstream services (Redis, IdP)
503	Service Unavailable	Server overloaded or restarting

Quick Diagnostics Checklist

For users:

[ ] Server URL is correct and includes /mcp path
[ ] OAuth endpoints are accessible in browser
[ ] Client configuration JSON is valid
[ ] Browser can reach authentication pages
[ ] Account has access to the server

For administrators:

[ ] All required environment variables are set
[ ] Redis is running and accessible
[ ] Identity provider is reachable from server
[ ] JWKS URL returns valid public keys
[ ] Health endpoint returns "status": "ok"
[ ] Logs don't show repeated errors
[ ] Disk space is available
[ ] Memory usage is within limits

Troubleshooting Guide ​

For Users ​

Connection Issues ​

"Cannot connect to MCP server" ​

"OAuth authentication failed" ​

"Token expired" or "Unauthorized" ​

"Invalid configuration" or "Invalid settings.json" ​

Tool/Prompt Issues ​

"Tool not found" or "Prompt not available" ​

"Tool execution failed" ​

Performance Issues ​

"Slow response times" ​

"Frequent disconnections" ​

Client-Specific Issues ​

Claude Desktop ​

Claude Code (VSCode) ​

GitHub Copilot ​

Microsoft Copilot ​

For Administrators ​

Startup Issues ​

"Server won't start" ​

"JWKS discovery failed" ​

Authentication Issues ​

"All requests return 401 Unauthorized" ​

"OAuth flow fails" ​

Redis Issues ​

"Session not found" errors ​

"Redis connection refused" ​

Performance Issues ​

"High memory usage" ​

"Slow API responses" ​

Security Issues ​

"Suspicious authentication attempts" ​

"Token leakage suspected" ​

Monitoring & Health Checks ​

Health Check Endpoint ​

Monitoring Recommendations ​

Logging & Debugging ​

Enable Debug Logging ​

Log Locations ​

Key Log Events ​

Getting Additional Help ​

For Users ​

For Administrators ​

Common Error Codes ​

Quick Diagnostics Checklist ​

Troubleshooting Guide

For Users

Connection Issues

"Cannot connect to MCP server"

"OAuth authentication failed"

"Token expired" or "Unauthorized"

"Invalid configuration" or "Invalid settings.json"

Tool/Prompt Issues

"Tool not found" or "Prompt not available"

"Tool execution failed"

Performance Issues

"Slow response times"

"Frequent disconnections"

Client-Specific Issues

Claude Desktop

Claude Code (VSCode)

GitHub Copilot

Microsoft Copilot

For Administrators

Startup Issues

"Server won't start"

"JWKS discovery failed"

Authentication Issues

"All requests return 401 Unauthorized"

"OAuth flow fails"

Redis Issues

"Session not found" errors

"Redis connection refused"

Performance Issues

"High memory usage"

"Slow API responses"

Security Issues

"Suspicious authentication attempts"

"Token leakage suspected"

Monitoring & Health Checks

Health Check Endpoint

Monitoring Recommendations

Logging & Debugging

Enable Debug Logging

Log Locations

Key Log Events

Getting Additional Help

For Users

For Administrators

Common Error Codes

Quick Diagnostics Checklist