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.

Error response status codes for tool calls and metadata

Apigee MCP endpoints return HTTP status codes that follow the Model Context Protocol (MCP) specification and related OAuth standards. Understanding this behavior helps you correctly handle errors in your MCP client or AI agent.

The following table summarizes the status codes returned by Apigee MCP endpoints:

Example: tool execution error response body

When a tool call fails, Apigee MCP returns HTTP 200 OK and reports the failure in the JSON-RPC result object, with isError set to true. The original error returned by your backend is preserved: the backend response body is placed verbatim (as a string) in result.content[].text. For example, if the backend returns HTTP 404 with the body {"error":"User 42 not found"}, the MCP response is:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

The id matches the id of your tools/call request. If the backend returns no response body, text contains a generated summary instead, such as Operation failed (HTTP 500).

Your MCP client should inspect result.isError (not the HTTP status code) to detect a failed tool call. If your client code specifically expects a 4xx or 5xx HTTP status to signal a tool execution error, it will no longer detect the error after this change, because the response is now HTTP 200 OK. Update such clients to read result.isError and the content array.

Protocol-level errors (for example, a malformed JSON-RPC request) are distinct from tool execution errors: they continue to be returned in the JSON-RPC error object (for example, {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) rather than in result.isError.

Recommendation: Standards-compliant MCP clients handle these status codes through their default logic, so no changes are required. If you previously added a client-side workaround to handle non-standard status codes—for example, parsing a non-2xx response body for tools/call errors, or treating a 500 response from the PRM endpoint as "metadata not configured"—we recommend removing that workaround. Otherwise, your client might continue to use obsolete handling logic instead of processing the corrected status codes normally.

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.

Cannot change API style to MCP in API Hub

If an API resource with existing API operations is already present in Apigee API hub, you cannot change the API style attribute for that resource to MCP. To register an API with Apigee API hub as an MCP API, you must select the MCP style when first registering the API, or ensure no operations are present on the API resource before changing the style to MCP.

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.