MCP Client Connection Troubleshooting

Common issues when connecting Reeva servers to MCP clients and how to fix them.

Connection Issues

Server Not Appearing

Symptoms:

• Server doesn't show in client's MCP panel
• No error message, just missing

Causes & Solutions:

1. Invalid JSON syntax

   // ❌ Wrong - trailing comma
   {
     "mcpServers": {
       "reeva": {
         "url": "...",
         "headers": {
           "Authorization": "Bearer ..."
         },
       }
     }
   }
   
   // ✅ Correct
   {
     "mcpServers": {
       "reeva": {
         "url": "...",
         "headers": {
           "Authorization": "Bearer ..."
         }
       }
     }
   }

2. Missing type field (for Claude Desktop)

   // ❌ Wrong - missing type
   {
     "mcpServers": {
       "reeva": {
         "url": "https://api.joinreeva.com/mcp/server_xxx",
         "headers": { "Authorization": "Bearer ..." }
       }
     }
   }
   
   // ✅ Correct - include type for Claude Desktop
   {
     "mcpServers": {
       "reeva": {
         "type": "sse",
         "url": "https://api.joinreeva.com/mcp/server_xxx",
         "headers": { "Authorization": "Bearer ..." }
       }
     }
   }

3. Client not restarted

   • Close the application completely
   • Reopen (don't just reload window)

4. Config file location wrong

   • Cursor: ~/Library/Application Support/Cursor/User/mcp-settings.json (Mac)
   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

"Failed to Connect" Error

Symptoms:

• Error message when client tries to connect
• Red/disconnected status indicator

Solutions:

1. Check server URL

   ✅ Correct: https://api.joinreeva.com/mcp/server_abc123
   ❌ Wrong: https://api.joinreeva.com/mcp/abc123
   ❌ Wrong: http://api.joinreeva.com/mcp/server_abc123 (http not https)

2. Verify server is active

   • Log into Reeva Dashboard
   • Go to Servers
   • Check server shows as "Active"
   • If deleted, won't connect

3. Network/firewall issues

   • Check client can access internet
   • Verify no corporate firewall blocking
   • Try from different network

Authentication Issues

"Authentication Failed"

Symptoms:

• Connection works but tools fail
• Error about invalid or missing API key

Solutions:

1. Verify Authorization header format

   // ✅ Correct format
   "headers": {
     "Authorization": "Bearer your_api_key_here"
   }
   
   // ❌ Wrong - missing "Bearer " prefix
   "headers": {
     "Authorization": "your_api_key_here"
   }
   
   // ❌ Wrong - extra quotes around key
   "headers": {
     "Authorization": "Bearer \"your_api_key_here\""
   }
   
   // ❌ Wrong - trailing space in key
   "headers": {
     "Authorization": "Bearer your_api_key_here "
   }

2. Check key status

   • Go to Reeva Dashboard → Servers → Your Server
   • Check Linked API Keys section
   • Verify key is listed and active (not revoked)

3. Key-server mismatch

   • Ensure API key is linked to the correct server
   • Server-specific keys only work for one server

4. Generate new key

   • If key lost or compromised
   • Create new key in dashboard
   • Update client configuration
   • Restart client

"Unauthorized" on Tool Execution

Symptoms:

• Server connects fine
• Tool calls fail with 401/403 errors

Causes:

• API key revoked mid-session
• Permission changes on server
• Key expired (rare)

Solutions:

• Generate fresh API key
• Verify server ownership
• Check server hasn't been transferred

Tool Availability Issues

"Tool Not Found"

Symptoms:

• AI says tool doesn't exist
• Specific tool missing from available tools

Solutions:

1. Verify tool in server

   • Dashboard → Servers → Your Server
   • Check "Selected Tools" list
   • Tool must be added to server

2. Check custom tool exists

   • Dashboard → Tools → My Tools
   • Verify custom tool hasn't been deleted
   • Re-create if necessary

3. Clear client cache

   • Sometimes clients cache old tool list
   • Restart client
   • Re-fetch tool list

AI Can't See Any Tools

Symptoms:

• AI says "I don't have access to any tools"
• MCP connection shows "Connected" but tools empty

Solutions:

1. Server has no tools

   • Check server in dashboard
   • Must have at least one custom tool
   • Add tools and restart client

2. MCP protocol issue

   • Test server in Reeva Chat (works?)
   • If Chat works but client doesn't: client issue
   • Update client to latest version

3. Permissions issue

   • Check client has permission to access network
   • macOS: System Preferences → Security → Network
   • Windows: Firewall settings

Execution Issues

"Insufficient Credits"

Symptoms:

• Tool execution starts but fails
• Error about not enough credits

Solutions:

• Check credit balance: Dashboard → Usage
• Purchase more credits
• Tool executed successfully despite error? (Check Usage logs)

Tools Execute But Fail

Symptoms:

• Tool runs but returns error
• Specific error message from external service

Debug Steps:

1. Test in Reeva Playground

   • Dashboard → Servers → Your Server → Playground
   • Try same tool with same parameters
   • See detailed error message

2. Check credentials

   • If tool requires auth (Notion, Jira, etc.)
   • Dashboard → Accounts
   • Verify credential is linked and active

3. Verify parameters

   • Check tool's input schema
   • Dashboard → Tools → [Tool Name]
   • Ensure required parameters provided

Slow Tool Execution

Symptoms:

• Tools take >30 seconds
• Client times out waiting

Expected delays:

• Web scraping: 5-30 seconds (normal)
• API calls: 1-5 seconds (normal)
• Database queries: 1-10 seconds (normal)

If consistently slow:

• Test in Playground (same speed?)
• Check network latency
• External service may be slow
• Contact support if persistent

Client-Specific Issues

Cursor

Issue: Server added but Cursor doesn't recognize

Solution:

1. Completely quit Cursor (Cmd+Q or Ctrl+Q)
2. Delete config file: ~/Library/Application Support/Cursor/User/mcp-settings.json (Mac)
3. Restart Cursor
4. Re-add configuration
5. Restart again

Issue: Tools work once then stop

Solution:

• Cursor may have cached connection
• Reload window: Cmd/Ctrl+Shift+P → "Reload Window"
• Or full restart

Claude Desktop

Issue: Server not recognized after adding config

Solution:

1. Verify config file location is correct for your OS
2. Ensure type field is set to "sse" or "http"
3. Completely quit Claude Desktop (not just close window)
4. Reopen Claude Desktop

Issue: Config file not found

Solution: Create the file and parent directories:

# macOS
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windsurf

Issue: Can't find MCP settings

Solution:

• Update Windsurf to latest version
• Config location: ~/.codeium/windsurf/mcp_config.json
• Create the file if it doesn't exist

Claude Code

Issue: claude mcp command not found

Solution:

# Verify installation
which claude

# Check Claude Code documentation for installation steps

Issue: Server not connecting

Solution:

# Re-add with correct format
claude mcp add --transport sse reeva https://api.joinreeva.com/mcp/server_xxx \
  --header "Authorization: Bearer YOUR_API_KEY"

Debug Checklist

When something doesn't work, verify:

• Server exists and is active in dashboard
• API key is correct (formatted as Bearer YOUR_KEY)
• Authorization header has proper format with "Bearer " prefix
• Server has at least one custom tool
• Custom tools haven't been deleted
• Credits balance is sufficient
• Client has been restarted (fully, not just reload)
• Network connection is working
• Client is up to date
• Config JSON syntax is valid
• Tested server works in Reeva Chat

Getting Detailed Logs

Cursor

1. Help → Toggle Developer Tools
2. Console tab
3. Look for MCP-related messages
4. Filter by "MCP" or "reeva"

Claude Desktop

1. Check for error messages in the chat
2. Restart to see connection errors on startup

Windsurf

1. View → Output
2. Select "MCP" from dropdown
3. Review connection attempts

Claude Code

# List servers and their status
claude mcp list

Still Stuck?

If you've tried everything:

1. Test in isolation

   • Create minimal test server with one tool
   • Use in fresh client install
   • Helps isolate problem

2. Check status page

   • Verify Reeva API is operational
   • No ongoing incidents

3. Contact support

   • Provide:
     • Server ID
     • Client and version
     • Error messages
     • Steps to reproduce
   • We'll help debug!

See Also

• Cursor Integration Guide
• Claude Desktop Integration Guide
• Claude Code Integration Guide
• Windsurf Integration Guide
• Common Errors
• FAQ