Troubleshoot MCP deployments in Apigee

This page applies to Apigee, but not to Apigee hybrid.

View Apigee Edge documentation.

This page describes how to troubleshoot and resolve issues with the deployment of MCP discovery proxies. You can use this page to understand the asynchronous provisioning lifecycle of MCP deployments, resolve error codes, and verify runtime connectivity.

Understand MCP deployment

The deployment of an MCP Discovery Proxy is an asynchronous, multi-step process that ensures the configuration is fully propagated across the Apigee and Google Cloud infrastructure before proxy deployment is complete.

While these downstream provisioning steps are taking place, the UI shows the proxy in a Provisioning status. When the process is complete, the status changes to Deployed. This status confirms that all downstream components are fully provisioned and the proxy is ready to handle traffic.

Troubleshooting

The following sections describe errors and known issues you might encounter while using MCP in Apigee.

CORS policy for browser-based MCP calls

A Cross-Origin Resource Sharing (CORS) policy is necessary when Apigee MCP calls are made directly from a browser (for example, when the MCP inspector uses the "Direct" setting instead of "Via Proxy"). The MCP Discovery Proxy template includes the Apigee CORS policy in the Proxy Endpoint Request PreFlow of the proxy bundle by default to enable browser-based calls.

If you encounter CORS-related issues when making calls directly from a browser, you may need to adjust the CORS policy settings in the Proxy Endpoint Request PreFlow of your MCP Discovery proxy bundle.

JSON parse error when sending request to MCP endpoint

You may receive an error message similar to the following (or with a different error code and message) when sending a request to your MCP endpoint: 

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

In that case, we recommend confirming the following information:

  • You have entered the correct MCP endpoint URL.
  • Your request is formatted correctly.
  • You are accessing a supported method.
  • You enabled and configured your MCP Discovery Proxy in a supported region. For a list of regions that may have capacity limits, see deployment failures.

Deployment failures

If deployment of your MCP Discovery Proxy fails with a Failed status in the UI, check the error message for more details. Common failures include:

  • Networking configuration failed or Unsupported Schema in OAS: These errors typically indicate a problem with your OpenAPI specification. Ensure your specification is valid and uses a supported version.
  • Region capacity limits: If you see an error related to load balancer provisioning failure, or the provisioning status never changes to Deployed, it might be due to temporary infrastructure capacity limits in one of the following regions:
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    To resolve the error, try deploying the proxy to an environment in a different region.

If you encounter any other issues, see Using debug for detailed information on using the Debug tool in the Google Cloud console to analyze requests and responses to and from your MCP Discovery Proxy.