Skip to main content

​
Deployment errors

​
Repository not found

Error: “No repositories found” or “Repository not accessible” Fix: Install the GitHub App and grant access to your repository.
  1. Go to Settings in your dashboard
  2. Click Install GitHub App
  3. Select the repositories you want to deploy
  4. Return to the dashboard and refresh

​
Build failed

Error: Deployment stuck at “Building” or shows “Build failed” Common causes:
  • Missing requirements.txt or pyproject.toml
  • Syntax errors in your code
  • Missing dependencies
Fix:
  1. Check build logs in your deployment details
  2. Ensure your code runs locally: python main.py
  3. Verify all dependencies are listed in your requirements file

​
Deployment timeout

Error: “Deployment timed out” or stuck at “Deploying” Cause: Server doesn’t start within 30 seconds. Fix:
  1. Ensure your server starts quickly
  2. Check for blocking operations at startup
  3. Verify your server listens on the correct port

​
Runtime errors

​
502/503 errors

Error: “Server unavailable” or bad gateway errors Fix:
  1. Check deployment logs for startup errors
  2. Verify your MCP server implements the protocol correctly
  3. Ensure the server responds to health checks at /health

​
Protocol errors

Error: “Invalid JSON-RPC” or MCP protocol errors Fix: Verify your server follows MCP spec: 
// Valid MCP response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": { "listChanged": true } },
    "serverInfo": { "name": "my-server", "version": "1.0.0" }
  }
}

​
Cold start delays

Symptom: First request takes several seconds on Free plan. Cause: Scale-to-zero servers sleep after 15 minutes of inactivity. Solutions:
  • Wait a few seconds for the server to wake up
  • Upgrade to a paid plan for always-on servers

​
Authentication errors

​
Invalid token

Error: 401 Unauthorized when OAuth is enabled Fix:
  1. Verify your token is valid and not expired
  2. Check the Authorization Server URL in deployment settings
  3. Ensure the token audience matches your server URL

​
Missing scopes

Error: 403 Forbidden with scope errors Fix: Ensure your token includes all required scopes configured in deployment settings.

​
Logs

​
Access build logs

  1. Go to your dashboard
  2. Click on a deployment
  3. View the Build Logs section

​
Access runtime logs

  1. Go to your dashboard
  2. Click on a deployment
  3. View the Runtime Logs section

​
Still stuck?

Contact Support

Email max@mcpdeploy.dev with your deployment ID and error details.