Skip to main content

​
Deployment Issues

​
GitHub App Not Installed

Error: “No repositories found” or “GitHub not connected” Solution:
  1. Go to mcpdeploy.dev/app
  2. Click “Settings” → “GitHub Integration”
  3. Install the MCP Deploy GitHub App
  4. Grant access to your repositories
  5. Return to the dashboard and refresh

​
Build Failed

Symptoms: Deployment stuck at “Building” or shows “Build failed” Common causes:
  • Missing dependencies file (requirements.txt, package.json)
  • Unsupported runtime or language
  • Syntax errors in your code
  • Missing environment variables
Solutions:
  1. Check your repository has a valid dependencies file
  2. Ensure your code runs locally: python main.py or npm start
  3. Check the build logs in the deployment details
  4. MCP Deploy handles all server endpoints automatically

​
Certificate Not Ready

Error: HTTPS certificate issues or “Certificate not ready” Solution: MCP Deploy uses automatic Let’s Encrypt certificates. This can take 1-2 minutes during beta.
  • Wait a few minutes and refresh
  • Check if your domain is accessible
  • Contact support if it persists after 5 minutes

​
Deployment Timeout

Error: “Deployment timed out” or stuck at “Deploying” Possible causes:
  • Server doesn’t start within 30 seconds
  • Health check failing
  • Port conflicts
Debug steps:
  1. Ensure your server runs locally with python main.py
  2. Check that your dependencies are properly specified
  3. Verify your MCP server follows the MCP protocol
  4. Check deployment logs for error messages

​
Repository Not Found

Error: “Repository not accessible” Solutions:
  • Ensure the repository is public or you’ve granted GitHub App access
  • Check repository permissions
  • Verify the repository exists and is not empty
  • Try refreshing the repository list

​
Runtime Issues

​
Server Not Responding

Symptoms: 502/503 errors, “Server unavailable” Check:
  • Is your server running locally?
  • Are you following the MCP protocol correctly?
  • Check deployment logs for startup errors

​
MCP Protocol Errors

Error: “Invalid JSON-RPC” or protocol errors Verify:
  • Your server accepts JSON-RPC 2.0 format
  • Required fields: jsonrpc, method, id
  • Proper response format for MCP methods
// Correct initialize response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": { "listChanged": true } },
    "serverInfo": { "name": "my-server", "version": "1.0.0" }
  }
}

​
CORS Issues

Error: CORS errors in browser console Solution: MCP Deploy handles CORS automatically. If you see CORS errors:
  • Ensure you’re using the correct HTTPS URL
  • Check if your client is sending proper headers
  • Try using a different MCP client

​
Performance Issues

​
Slow Response Times

During beta:
  • Cold starts may take longer
  • Beta platform may have variable performance
  • Rate limiting applies to beta accounts
Optimizations:
  • Keep your server lightweight
  • Use efficient dependencies
  • Monitor your usage in the dashboard

​
Rate Limiting

Error: “Too many requests” or 429 errors Beta limits:
  • Basic usage monitoring
  • Check your usage in the dashboard
  • Upgrade to paid plans for higher limits

​
Logs and Monitoring

​
Accessing Logs

  1. Go to your dashboard
  2. Click on a deployment
  3. View “Build Logs” and “Runtime Logs” tabs
  4. Basic logs are available in the dashboard

​
Testing Your Deployment

Connect your MCP client to the HTTPS URL provided after deployment. MCP Deploy handles all server endpoints automatically.

​
Getting Help

​
Beta Support

During beta, we’re here to help:

​
Debug Information

When reporting issues, include:
  • Deployment ID
  • Repository URL
  • Error messages from logs
  • Steps to reproduce
  • Your MCP client and version

​
Common MCP Client Issues

​
Claude Desktop

Connection failed:
  • Use the HTTPS URL from your deployment
  • Ensure your MCP server is healthy
  • Check Claude Desktop logs

​
VS Code Extensions

Plugin not working:
  • Verify the MCP endpoint URL
  • Check extension logs
  • Ensure compatible MCP protocol version

​
Still Having Issues?

Check Status

Service status and incidents.

Contact Support

Get help from our team.

GitHub Issues

Report bugs or request features.