Troubleshooting

"Repository not found" or access denied

This occurs when DeployContext cannot access your GitHub repository.

• Verify that the repository URL is correct and publicly accessible
• For private repositories, ensure you have connected your GitHub account with the repo scope
• Check that the branch you specified exists in the repository

Deployment times out

Deployments that exceed the time limit may be caused by large repositories or complex builds.

• Check the deployment logs in your dashboard for specific errors
• Ensure your repository does not contain excessively large files or dependencies
• Verify that your build command completes successfully when run locally

"Runtime not detected"

DeployContext auto-detects your runtime from your repository files.

• For Node.js: ensure a package.json is present at the repository root
• For Python: ensure a pyproject.toml or requirements.txt is present
• For Bun: ensure a bun.lockb file is present

OAuth authorization fails or redirects incorrectly

• Ensure your client is using PKCE (S256 code challenge) as it is mandatory for all flows
• Verify the redirect_uri matches exactly what was registered during dynamic client registration
• Check that your authorization request includes the required resource parameter for the target MCP server

Access token rejected or expired

• Access tokens expire after 1 hour. Use your refresh token to obtain a new one via the POST /oauth/token endpoint
• Refresh tokens expire after 30 days. If expired, re-authorize through the full OAuth flow
• Verify that the token's aud (audience) claim matches the MCP server you are calling

API key not working

• Confirm the API key format is correct: mcp_[base64url]_[checksum]
• Ensure the API key is being sent in the Authorization: Bearer header
• Verify you have an active subscription to the MCP you are trying to access
• Regenerate the key from your subscriber dashboard if issues persist

Node.js build fails

• Check that all dependencies are listed in package.json (not just installed locally)
• Ensure a valid main or start script entry point is defined
• If using TypeScript, verify that tsconfig.json is present and the build compiles without errors locally
• Lock files (package-lock.json) are generated if missing, but including one is recommended

Python build fails

• Ensure pyproject.toml or requirements.txt lists all dependencies
• Verify the entry point file is correctly specified and uses FastAPI or the MCP SDK
• Check that your Python version is compatible (3.10+ recommended)
• For detailed guidance, see the Python deployment guide

Database setup errors

• Ensure your CSV file is properly formatted with headers matching your schema
• Check that the CSV encoding is UTF-8
• Database credentials are injected as environment variables automatically; do not hardcode connection strings

SSE connection drops or times out

• SSE connections require session affinity. DeployContext handles this automatically, but network proxies may interfere
• Check that your client supports reconnection on SSE stream interruption
• If using Claude Desktop, verify the endpoint URL in your configuration matches the one shown in your dashboard

stdio bridge not working

• The stdio bridge should activate automatically for MCPs that use standard input/output
• Check deployment logs for bridge initialization errors
• Verify that your MCP reads from stdin and writes to stdout in the expected MCP protocol format

MCP tools not appearing in Claude Desktop

• Confirm the endpoint URL is correct in your Claude Desktop configuration file
• Restart Claude Desktop after changing the configuration
• Test the MCP endpoint directly with the MCP Inspector to verify it responds correctly
• Check that the MCP server registers its tools during initialization

HTTP 429 Too Many Requests

• MCP endpoints are rate limited to 60 requests per minute per API key at the edge
• Implement exponential backoff in your client when receiving 429 responses
• If you consistently hit rate limits, consider upgrading your platform subscription for higher limits
• See the API Reference for plan-specific rate limits