Apigee Hybrid MCP: Run Agent Tools Inside Your Kubernetes Cluster

Google announced MCP support for Apigee hybrid on October 14, 2026. The capability ships in Apigee hybrid 1.17.0, which was released on September 14, 2026, and lets organizations expose existing APIs as Model Context Protocol tools while keeping the MCP request path inside their own Kubernetes cluster.

This is useful for enterprises that already use Apigee hybrid because of data residency, network isolation, regulatory or multi-cloud requirements. An OpenAPI 3.0.x document becomes the source for discoverable tools, agents call a managed /mcp endpoint over JSON-RPC, and Apigee applies the gateway policies and observability controls around those calls.

Fact versus recommendation: release dates, architecture, configuration fields, limits and security behavior in this guide come from Google Cloud documentation. The rollout sequence, testing plan and operational thresholds are Rubic8 recommendations, not Google requirements or independent performance benchmarks.

What Google Actually Released

Google's October 14 announcement describes the operational story around a feature that first appeared in the Apigee hybrid 1.17.0 release notes on September 14. These are two different dates: September 14 is the software release date; October 14 is the detailed developer announcement.

Apigee takes an OpenAPI 3.0.x specification and creates an MCP Discovery Proxy. Operations in the specification become tools that compatible agents can discover with tools/list and invoke with tools/call. Apigee performs the JSON-RPC handling and API transcoding, so teams do not need to build and maintain a separate MCP server for each API.

The hybrid-specific change is placement. The MCP data plane runs inside the customer's Kubernetes cluster. Google's control plane generates tool configuration from the OpenAPI specification, and a sidecar in the cluster periodically pulls that configuration. Google says MCP request and response traffic does not cross into the Google-managed control plane at request time.

Apigee SaaS and Apigee Hybrid Are Not the Same Deployment

This distinction matters when estimating cost. Google publishes Pay-as-you-go rates for hosted Apigee, but its Pay-as-you-go FAQ explicitly says that pricing model does not apply to Apigee hybrid. The hybrid MCP documentation does not publish a separate per-tool MCP price. Treat the cost as part of your Apigee hybrid commercial agreement plus the Kubernetes compute, storage, networking, observability and operations you manage. Confirm contract-specific charges with your Google Cloud account team rather than applying hosted rates to hybrid.

Architecture: From OpenAPI Operation to Agent Tool Call

1. An OpenAPI specification defines the tool surface

Apigee MCP supports OpenAPI 3.0.0 through 3.0.3. Tool names, descriptions, parameters and request bodies are derived from the specification, which makes API description quality an agent-safety concern. An ambiguous operation description can cause the model to select the wrong tool even when the gateway behaves correctly.

Before publishing a specification, make operation IDs unique and stable, describe side effects plainly, document required identifiers and avoid exposing internal operations that an agent should never call.

2. The Discovery Proxy exposes one MCP endpoint

Agents connect to the MCP Discovery Proxy over HTTP/S and JSON-RPC. The endpoint supports tools/list for discovery and tools/call for execution. The proxy handles policy enforcement before routing calls to the in-cluster MCP data plane and the underlying API.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

A tool invocation uses the tool name returned by discovery:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "check_order_status",
    "arguments": {
      "orderId": "ORD-1042"
    }
  }
}

During testing, Rubic8's JSON Formatter can make JSON-RPC payloads easier to inspect, while the JSON Validator can catch syntax errors. Valid JSON does not prove that authorization, tool selection or business rules are correct, so keep those checks in the gateway and backend.

3. Existing Apigee policies govern the request

The gateway can authenticate the caller, authorize tools through API products, apply quotas and other policies, then route the translated request to the backend. This lets platform teams reuse established API governance instead of creating a parallel security layer solely for agents.

Prerequisites and Compatibility Checklist

Before enabling the feature, verify all of the following:

• Every participating cluster runs Apigee hybrid 1.17.0 or later.
• The Kubernetes version and platform are supported for your exact Apigee hybrid release.
• You have a Subscription or Evaluation Apigee hybrid organization.
• The target API has a valid OpenAPI 3.0.0–3.0.3 specification.
• All clusters serving the same environment group can be enabled consistently.
• A maintenance window is approved for the staged canary release triggered by enablement.
• The cluster has capacity for the MCP pods and autoscaling range.
• A network policy can restrict access to the in-cluster MCP service.
• Authentication and tool-level authorization requirements are documented before deployment.

Do not rely only on the product version label. Check Google's current supported-platform matrix, because supported Kubernetes versions change over time.

How to Enable MCP in Apigee Hybrid

Google documents MCP as optional and disabled by default. At a high level, enabling it requires a one-time control-plane access grant for the existing apigee-watcher identity and a Helm configuration change.

Set the top-level feature flag

Add the following top-level field to overrides.yaml. It belongs at the same level as fields such as instanceID and org, not inside the mcpServer object.

instanceID: "YOUR_INSTANCE_ID"
org: "YOUR_ORGANIZATION_NAME"
enableMcpServer: true

Upgrade the Helm charts in the documented order

Upgrade the apigee-operator chart first and the apigee-org chart second. The operator owns the schema for the new MCP resources. Google's announcement warns that reversing the order can produce an apparently successful upgrade without MCP pods.

Changing enableMcpServer triggers a staged canary release of Message Processor pods. Schedule both enablement and any later disable operation within an approved maintenance window, monitor the rollout and keep a rollback plan.

Verify the data plane before deploying tools

Confirm that the MCP pods are ready, the service is reachable only from the intended Message Processor pods, the sidecar can retrieve configuration and all clusters in the environment group are consistent. Only then deploy an MCP Discovery Proxy using Google's MCP quickstart.

The Most Important Security Caveat

In Apigee hybrid 1.17.0, the in-cluster MCP data plane does not independently authenticate callers. It trusts that traffic has already passed through an Apigee MCP proxy running in Message Processor. That means an unintended in-cluster workload that can reach the MCP Service on TCP 443 could invoke tools without a second authentication check at the data plane.

Google recommends restricting ingress to pods labeled app=apigee-mcp-server so that only Message Processor pods labeled app=apigee-runtime in the same namespace can connect. Use the policy engine already approved for your platform, such as Kubernetes NetworkPolicy, Cilium, Calico or Istio AuthorizationPolicy.

This network boundary should complement, not replace, authentication and authorization at the Discovery Proxy. Mutating tools also need application-level safeguards. MCP clients are responsible for human oversight of tool invocations; the protocol and gateway do not automatically decide when a user must approve a destructive action.

Authorization and Tool Exposure

API products can restrict which tools a client may discover and call. Build separate products for read-only tools and state-changing tools instead of placing every operation behind one broad credential. Start with a narrow allowlist, test tools/list under each client identity and verify that an unauthorized tool is both hidden from discovery and blocked during direct invocation.

Google's current implementation supports tools/list and tools/call. The ParsePayload policy parses JSON-RPC request bodies and has a 10 MB default request-body limit, configurable up to 30 MB. MCP error responses do not support Server-Sent Events through GET; those calls return HTTP 405.

Monitoring, Tracing and Operations

All tool calls share the /mcp route, but Apigee attaches MCP-specific analytics fields so operators can filter traffic by API style and tool name. API insights can show total traffic, response time, transactions per second, payload-size percentiles, errors and target performance for individual tools.

There are eligibility limits: API insights is not available for organizations using VPC Service Controls or Data Residency. For hybrid deployments, the dashboard is calculated from Message Processor traffic; logs from the in-cluster MCP data plane must be collected through your normal cluster log pipeline.

Apigee can also translate W3C trace context carried in the JSON-RPC _meta field into conventional traceparent and tracestate headers. Instrumented backends can then join the same trace without learning MCP-specific metadata conventions.

Current Limits to Design Around

• Hosted Apigee limits an organization to 1,000 MCP tools.
• Apigee hybrid is bounded by specification, proxy bundle and tools/list response sizes rather than one fixed tool count.
• Google says a typical hybrid organization may fit about 10,000 tools with default response-size limits, but actual capacity depends heavily on parameters, request bodies and description length.
• All clusters serving one environment group must enable MCP uniformly; otherwise traffic reaching a cluster without MCP returns 503.
• Version 1.17.0 uses one-way TLS between Message Processor and the MCP data plane.
• There is one MCP data plane per Apigee organization per cluster.
• CPU and memory sizing for hybrid MCP pods is customer-managed.

Treat the approximate 10,000-tool figure as planning guidance, not a guaranteed quota. Run Google's capacity estimator against your specifications and test the real tools/list response size before publishing a large catalog.

A Safe Production Rollout Plan

Phase 1: Start with one read-only API

Choose a low-risk API such as order status or service health. Remove unused operations from the specification, improve descriptions and expose only the minimum fields an agent needs.

Phase 2: Test identity boundaries

Create separate test clients for allowed and denied roles. Verify discovery results, direct calls, expired tokens, missing scopes, oversized payloads and malformed JSON-RPC requests. Confirm that cluster network policy blocks a pod that is not a Message Processor.

Phase 3: Measure the whole path

Capture proxy overhead, backend latency, tool errors, authorization failures and request/response sizes. Tool-level metrics matter more than aggregate /mcp latency because one slow backend can otherwise make the entire MCP endpoint look unhealthy.

Phase 4: Add mutating tools carefully

For operations such as refunds, account changes or deployments, require explicit user confirmation in the client, idempotency controls in the API and audit records in the backend. Do not assume that a precise tool description prevents an AI model from selecting it incorrectly.

Phase 5: Rehearse rollback

Disabling MCP is a Helm change that triggers another staged canary release. Test the rollback procedure before an incident. Remember that deployed Discovery Proxies remain in the control plane after disabling the in-cluster data plane; undeploy them if you need to fully remove the exposed configuration.

When Apigee Hybrid MCP Is a Good Fit

The strongest fit is an organization that already operates Apigee hybrid, has governed APIs and needs agents to call them without moving the runtime data path outside its infrastructure. It is especially relevant to regulated, on-premises and multi-cloud environments where network boundaries are a first-class architectural constraint.

It is a weaker fit for a small team with only a few simple tools and no existing Apigee footprint. Apigee hybrid remains an enterprise API management platform with Kubernetes and operational responsibilities. A lightweight MCP server may be easier when the organization does not need centralized policy, analytics, catalog integration or hybrid placement.

Frequently Asked Questions

Does MCP request traffic go to Google's control plane?

Google says the hybrid runtime request path stays inside the customer's cluster. The cluster sidecar makes outbound requests to pull tool configuration from the Google-managed control plane.

Does Apigee hybrid support every OpenAPI version?

No. The current MCP documentation lists OpenAPI 3.0.0, 3.0.1, 3.0.2 and 3.0.3.

Is MCP enabled automatically after upgrading to 1.17.0?

No. It is disabled by default and requires the control-plane access grant, enableMcpServer: true and Helm chart upgrades in the documented order.

Is there a separate published MCP price for Apigee hybrid?

Google's public hybrid MCP documentation does not list a separate per-tool price. Hybrid is not available under Apigee Pay-as-you-go pricing, so confirm charges under your subscription or evaluation terms and include your own cluster operating costs.

Can the in-cluster MCP service authenticate callers itself?

Not in version 1.17.0. It relies on Message Processor for caller identity, which is why Google recommends an ingress policy that limits service access to Message Processor pods.

Final Recommendation

Apigee hybrid MCP is more than a protocol adapter: it is a way to apply existing API governance to agent tools while preserving an in-cluster runtime path. The architectural benefit is meaningful, but it does not remove the need for careful specifications, narrow authorization, network isolation, human approval for side effects and tool-level monitoring.

Start with one read-only API, validate the data path and identity boundaries, then expand only after the analytics and rollback process work. That approach tests the value of agent access without turning every enterprise API into a tool on day one.