Apigee Configuration

Prev Next

This page describes how to configure the PlainID Authorizer's Shared Flows in Google Apigee: which Shared Flows to deploy, which settings they read, and how to attach them to API proxies for four capabilities:

  1. Authorize APIs
  2. Authorize MCP and tools
  3. Agent dynamic discovery
  4. MCP dynamic discovery

The Authorizer is modular. Each capability comes from its own Shared Flow, so you deploy only the Shared Flows for the capabilities you choose. The choice applies per proxy: one proxy can use enforcement and Insights together, while another uses Insights alone.

Ensure that you set up the Apigee POP before continuing. See POP Setup for more information.

Prerequisites

The following are required:

  • An Apigee X organization with the API proxies or MCP servers to protect.
  • An Apigee Environment of type Intermediate or Comprehensive.
    Type Base does not support Shared Flows.
  • Permissions in Apigee to deploy Shared Flows, manage Environment resources, key value maps, and TLS keystores, and update API proxies.
  • A PlainID Environment with access to the PDP (Runtime) endpoint.
  • A Scope in PlainID with a Client ID and Client Secret.
  • To authorize MCP and tools, an Asset Type for MCP tools (default MCP-TOOL) and Policies that grant access to it. See Tools and MCP for more information.
  • For MCP dynamic discovery or Insights, an Apigee POP and its certificate files. See POP Setup for more information.
  • For MCP servers, an https:// endpoint with a certificate from a public certificate authority.

Only the prerequisites for the chosen capabilities apply.

Step 1: Deploy the Shared Flows

Deploy the Shared Flows for the chosen capabilities to each Environment where the proxies run.

Capability Shared Flow Position in the proxy
Authorize APIs plainid-authz-apigee Proxy endpoint PreFlow
Authorize MCP and tools, and MCP dynamic discovery plainid-mcp-bundle Last step in the PreFlow Request of each target endpoint
Agent dynamic discovery (Insights) plainid-insights-discoverer First step in the PreFlow Request of each target endpoint

Keep the Shared Flow names that come from the bundles, because the Flow Callouts reference them. Deploy the Shared Flows before deploying any proxy that calls them. To upgrade a Shared Flow, deploy the new bundle as a new revision. The proxies that call it don't need to change.

For the steps, see Creating reusable shared flows in the Apigee documentation.

Step 2: Configure the Apigee Environment

The MCP and Insights Shared Flows read their settings from three resources in the Apigee Environment. The Shared Flow that authorizes APIs reads its settings from flow variables set in the proxy (see Authorize APIs).

Resource Name Required for
Property set plainid Authorize MCP and tools, MCP dynamic discovery, Insights
Encrypted key value map plainid, with key clientSecret Authorize MCP and tools with authMethod=secret
TLS keystore plainid-collector, with one alias per proxy MCP dynamic discovery, Insights

The MCP and Insights Shared Flows look up each setting in this order: a plainid.<key> Flow Callout parameter, then the plainid property set, then the default.

Property Set plainid

Create an Environment-scoped property set named plainid with the keys for the chosen capabilities. Changes to the property set apply without redeploying the proxy. For the steps, see Using property sets in the Apigee documentation.

Authorize MCP and tools, and MCP dynamic discovery (plainid-mcp-bundle):

Key Default Used by Description
discoveryEnabled false Discovery Posts tools/list results to the PlainID collector.
enforcementEnabled false Enforcement Authorizes tools/call and filters tools/list. Explicit opt-in.
collectorUrl None Discovery The full PlainID collector endpoint URL. Must use https://.
pdpUrl None Enforcement The PDP Runtime base URL, for example https://<host>/api/runtime.
clientId None Enforcement The Client ID from the PlainID Scope.
authorizerId None Enforcement Optional. Adds X-Authorizer-Meta to PDP calls.
authMethod secret Enforcement secret authenticates with the Client Secret from the plainid key value map. token uses the end-user token only.
runtimeFineTune {} Enforcement JSON merged into meta.runtimeFineTune of each PDP request. The Shared Flow adds assetContext.
toolsResourceType MCP-TOOL Enforcement The PlainID Asset Type of MCP tools.
mcpErrorCode -32603 Enforcement The JSON-RPC error code returned on deny.
mcpErrorMessage Access Denied Enforcement The JSON-RPC error message returned on deny.
identityTokenHeader Authorization Enforcement The request header that carries the end-user token.
identityTokenVariable None Enforcement A flow variable that carries the end-user token. Takes precedence over identityTokenHeader. Use it when the proxy exchanges or replaces the token.
mcpServerName The target endpoint name Discovery The MCP server name in PlainID. Usually set per target endpoint as a Flow Callout parameter (see Enable MCP Dynamic Discovery and Insights).
debugEnabled false Both Writes diagnostics to the Apigee Debug tool, with credentials masked. Keep it false in production.

Insights (plainid-insights-discoverer):

Key Default Description
insightsEnabled false Posts every request on the proxy to the PlainID collector.
collectorUrl None The full PlainID collector endpoint URL. Must use https://. Shared with MCP dynamic discovery.
debugEnabled false Writes diagnostics to the Apigee Debug tool, with credentials masked. Shared with MCP dynamic discovery and enforcement.

Do not store the Client Secret in the property set.

Example plainid.properties:

discoveryEnabled=true
enforcementEnabled=true
insightsEnabled=true
collectorUrl=https://<host>/collector
pdpUrl=https://<host>/api/runtime
clientId=PYX9B9H5S29IBG9OEISG
authMethod=secret
toolsResourceType=MCP-TOOL
debugEnabled=false

Key Value Map plainid

Required only to authorize MCP and tools with authMethod=secret. Create an encrypted Environment key value map named plainid with an entry whose key is clientSecret and whose value is the Client Secret. The Shared Flow caches the value for 5 minutes, so a new secret can take up to 5 minutes to apply. For the steps, see the key value maps section of the Apigee documentation.

TLS Keystore plainid-collector

Required for MCP dynamic discovery and Insights. The Shared Flows authenticate to the PlainID collector with the certificate from the Apigee POP. The Environment needs a TLS keystore named plainid-collector with one alias for each proxy that reports to PlainID. The alias name must match the proxy name exactly. MCP dynamic discovery and Insights on the same proxy share the same alias. See POP Setup for the alias requirements.

Step 3: Apply the Shared Flows

Authorize APIs

The Shared Flow that authorizes APIs is the Authorizer you create and download from the Platform.

To configure the Shared Flow:

  1. Deploy the Authorizer bundle as a Shared Flow, as described in Step 1.
  2. In the Shared Flow's call-pdp policy, set the pdpEndpointV5 property:
    • For the Platform Cloud PDP: /api/runtime/5.0/decisions/permit-deny
    • For a customer-hosted Policy Authorization Agent (PAA) PDP: /runtime/5.0/decisions/permit-deny
  3. Deploy the Shared Flow.

call-pdp.xml for the Platform Cloud PDP:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript continueOnError="false" enabled="true" timeLimit="2000" name="call-pdp">
  <DisplayName>call-pdp</DisplayName>
  <IncludeURL>jsc://URI.js</IncludeURL>
  <IncludeURL>jsc://parse-headers.js</IncludeURL>
  <IncludeURL>jsc://parse-body.js</IncludeURL>
  <ResourceURL>jsc://call-pdp.js</ResourceURL>
  <Properties>
    <Property name="pdpEndpointV5">/api/runtime/5.0/decisions/permit-deny</Property>
    <Property name="authorizerVersion">1.3.4</Property>
  </Properties>
</Javascript>

For a customer-hosted PAA, use the same file with <Property name="pdpEndpointV5">/runtime/5.0/decisions/permit-deny</Property>.

To attach the Shared Flow to an API proxy:

  1. Add an AssignMessage policy that sets the configuration flow variables described below.
  2. Add a Flow Callout policy that calls the Authorizer Shared Flow.
  3. Add both as steps in the proxy endpoint PreFlow, the AssignMessage policy first.
  4. Deploy the proxy.

For the steps, see Creating reusable shared flows in the Apigee documentation.

Example:

<AssignMessage name="set-authz-config">
  <AssignVariable><Name>pdpUrl</Name><Value>https://acme-financing.us1.plainid.io</Value></AssignVariable>
  <AssignVariable><Name>clientId</Name><Value>PABCDYDO123J1T36MRMU</Value></AssignVariable>
  <AssignVariable><Name>authorizerId</Name><Value>APJJIUH1BFLOWOW</Value></AssignVariable>
  <AssignVariable><Name>authMethod</Name><Value>secret</Value></AssignVariable>
  <AssignVariable><Name>runtimeFineTune</Name><Value>{"includeIdentity": "true"}</Value></AssignVariable>
</AssignMessage>

<FlowCallout continueOnError="false" enabled="true" name="FC-PlainID-AuthZ">
  <DisplayName>FC-PlainID-AuthZ</DisplayName>
  <SharedFlowBundle>plainid-authz-apigee</SharedFlowBundle>
</FlowCallout>

Store the Client Secret in an Apigee key value map and assign it to the clientSecret flow variable, rather than writing it in the policy XML.

Configuration Flow Variables

Variable Required Default Description
pdpUrl Yes None The PDP base URL, for example https://pdp.example.com.
clientId Yes None The Client ID from the PlainID Scope.
authorizerId Yes None The Authorizer ID from the API Authorizers tab in the PlainID Environment.
authMethod No secret secret or token.
clientSecret When authMethod is secret None The Client Secret from the PlainID Scope.
runtimeFineTune No {} A JSON string of PDP fine-tune parameters, for example {"entityAttributes": {"region": ["US"]}, "combinedMultiValue": true}. See Authorization APIs for supported properties.
headerKeysCaseHandling No preserveCase Header key case: lowercase, uppercase, or preserveCase.
headerValuesCaseHandling No preserveCase Header value case: lowercase, uppercase, or preserveCase.
ignoreHeadersValueTransformation No None A comma-separated list of header names to exclude from case transformation.
propagateJwt No false true stores the PDP authorization JWT on Permit, so the proxy can forward it. See JWT Propagation.
responseJwtFlowVariable No None The flow variable that stores the authorization JWT on Permit. If unset or blank, the Authorizer doesn't store the JWT, even when propagateJwt is true.
debugPdpLogs No false Writes PDP request and response diagnostics to the Apigee Debug tool, with tokens and secrets masked.

JWT Propagation

To forward the authorization JWT, set propagateJwt to true and name a flow variable in responseJwtFlowVariable. When propagation is on, the Authorizer initializes that variable to an empty string before calling the PDP, so later policies can reference it safely even when the PDP returns standard JSON.

Set the variables before the Flow Callout:

<AssignMessage name="set-authz-config">
  <AssignVariable><Name>propagateJwt</Name><Value>true</Value></AssignVariable>
  <AssignVariable><Name>responseJwtFlowVariable</Name><Value>plainid.decision.jwt</Value></AssignVariable>
  <!-- plus pdpUrl, clientId, authorizerId, and the other configuration variables -->
</AssignMessage>

Forward the JWT to the backend (target endpoint PreFlow, after the Flow Callout):

<AssignMessage name="add-jwt-to-backend">
  <AssignTo createNew="false" type="request">request</AssignTo>
  <Set>
    <Headers>
      <Header name="X-Authorization-Decision">{plainid.decision.jwt}</Header>
    </Headers>
  </Set>
  <Condition>plainid.decision.jwt != null and plainid.decision.jwt != ""</Condition>
</AssignMessage>

Return the JWT to the client (proxy endpoint PostFlow Response), for example when testing:

<AssignMessage name="add-jwt-to-client-response">
  <AssignTo createNew="false" transport="http" type="response"/>
  <Set>
    <Headers>
      <Header name="X-Authorization-Decision">{plainid.decision.jwt}</Header>
    </Headers>
  </Set>
  <Condition>plainid.decision.jwt != null and plainid.decision.jwt != ""</Condition>
</AssignMessage>

Authorize MCP and Tools

plainid-mcp-bundle authorizes tools/call and filters tools/list to the caller's entitlements. With MCP dynamic discovery on, it also posts the full tool list to PlainID. You switch discovery and enforcement on independently in the property set. Both are off by default.

This example uses one MCP proxy with base path /mcp that fronts two MCP servers, context7 and mslearn. Each MCP server has its own target endpoint, and requests route by path suffix, for example /mcp/context7. Remove the FC-PlainID-Insights step if Insights isn't needed.

The proxy needs:

  • The policies listed below.
  • One target endpoint per MCP server. FC-PlainID-MCP must be the last step in its PreFlow Request. Other target policies, such as backend authentication, run before it.
  • A proxy endpoint with base path /mcp, a route rule per MCP server, and a DefaultFaultRule.
  • Client authentication (for example VerifyAPIKey, OAuthV2, or VerifyJWT) in the proxy endpoint, before routing.
  • Response streaming off.

For how to create and deploy API proxies, see the Apigee documentation.

Policies:

<!-- Keeps Apigee from appending the path suffix to the MCP server URL -->
<AssignMessage continueOnError="false" enabled="true" name="AM-MCP-NoPathSuffix">
  <DisplayName>AM-MCP-NoPathSuffix</DisplayName>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<FlowCallout continueOnError="true" enabled="true" name="FC-PlainID-Insights">
  <DisplayName>FC-PlainID-Insights</DisplayName>
  <SharedFlowBundle>plainid-insights-discoverer</SharedFlowBundle>
</FlowCallout>

<!-- continueOnError stays false: the Shared Flow's replies are faults -->
<FlowCallout continueOnError="false" enabled="true" name="FC-PlainID-MCP">
  <DisplayName>FC-PlainID-MCP</DisplayName>
  <SharedFlowBundle>plainid-mcp-bundle</SharedFlowBundle>
</FlowCallout>

Target endpoint (one per MCP server; the steps must run in this order):

<TargetEndpoint name="context7">
  <PreFlow name="PreFlow">
    <Request>
      <Step><Name>FC-PlainID-Insights</Name></Step>   <!-- first -->
      <Step><Name>AM-MCP-NoPathSuffix</Name></Step>
      <Step><Name>FC-PlainID-MCP</Name></Step>        <!-- last -->
    </Request>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPTargetConnection>
    <URL>https://mcp.context7.com/mcp</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

For the second server, use the same XML with name="mslearn" and its own URL. Put the full MCP server URL in <URL>. A <Path> element doesn't stop Apigee from appending the path suffix.

Proxy endpoint:

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <DefaultFaultRule name="plainid-mcp">
    <!-- Optional: response policies that must also apply to tools/list, for example CORS -->
    <Step>
      <Name>AM-CORS-Headers</Name>
      <Condition>plainid.mcp.respond == "true"</Condition>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>
  <HTTPProxyConnection>
    <BasePath>/mcp</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="context7">
    <Condition>proxy.pathsuffix MatchesPath "/context7" or proxy.pathsuffix MatchesPath "/context7/**"</Condition>
    <TargetEndpoint>context7</TargetEndpoint>
  </RouteRule>
  <RouteRule name="mslearn">
    <Condition>proxy.pathsuffix MatchesPath "/mslearn" or proxy.pathsuffix MatchesPath "/mslearn/**"</Condition>
    <TargetEndpoint>mslearn</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

The Shared Flow returns its own replies (denials and filtered tool lists) as faults with HTTP status 200. Response policies that must apply to them go in the DefaultFaultRule, with the condition on each step, because Apigee ignores a rule-level condition there. A custom FaultRule that rewrites responses must exclude plainid.mcp.respond == "true".

If a target policy before FC-PlainID-MCP replaces the Authorization header with a backend credential, set identityTokenVariable to a flow variable that still holds the end-user token, or set identityTokenHeader to the header that does.

With this configuration, Apigee handles each MCP request as follows:

Request Enforcement on Enforcement off
tools/call The PDP evaluates the tool name and arguments. Permit: the request continues to the MCP server. Anything else: HTTP 200 with a JSON-RPC error, for example {"jsonrpc":"2.0","id":<id>,"error":{"code":-32603,"message":"Access Denied"}}. The MCP server isn't called. Passes through.
tools/list The PDP returns the entitled tool names. The Shared Flow fetches tools/list from the MCP server, posts the full list to PlainID when MCP dynamic discovery is on, and returns only the entitled tools. A PDP failure returns an empty list. With MCP dynamic discovery on, the Shared Flow fetches the list, posts it to PlainID, and returns it unchanged. Otherwise, passes through.
Malformed POST body or JSON-RPC batch JSON-RPC error with id: null. Passes through.
initialize, ping, prompts/*, resources/*, GET, DELETE Passes through. Passes through.

Enable MCP Dynamic Discovery and Insights

MCP dynamic discovery and Insights run alongside enforcement or on their own. Insights provides agent dynamic discovery by reporting the traffic on each proxy to PlainID.

  • MCP dynamic discovery: set discoveryEnabled=true and collectorUrl in the property set. FC-PlainID-MCP then registers the MCP server's full tool list each time an agent calls tools/list.
  • Insights: set insightsEnabled=true and collectorUrl in the property set, and add FC-PlainID-Insights as the first step in the PreFlow Request of each target endpoint. This works on REST and MCP proxies.

Both capabilities need a plainid-collector keystore alias named after the proxy.

Insights runs in the target endpoint because the MCP server name and destination URL exist only after routing. Insights doesn't report requests that the proxy endpoint rejects, for example through authentication or a Quota policy. On MCP proxies, Insights reports denied tools/call requests, because it runs before plainid-mcp-bundle. FC-PlainID-Insights uses continueOnError="true", so a collector error doesn't block the request.

Each Insights report includes the timestamp, source IP, MCP server or target name (source_id), proxy name (service_name), destination URL, request URL, request headers (including credentials), and request body. It carries no user or agent identity. The collector reads the Tenant, Environment, and POP from the certificate.

The following settings adjust MCP dynamic discovery and Insights for individual proxies:

  • MCP server name. PlainID names each MCP server after its target endpoint. To use a different name, set <Parameter name="plainid.mcpServerName">orders-mcp</Parameter> on both FC-PlainID-MCP and FC-PlainID-Insights in that target endpoint, so discovery and Insights records match. If only some target endpoints need it, create separate copies of the policies, for example FC-PlainID-MCP-Orders and FC-PlainID-Insights-Orders.
  • Turn off Insights for one proxy. Add <Parameter name="plainid.insightsEnabled">false</Parameter> to its FC-PlainID-Insights policy.
  • Turn everything off without removing it. Set discoveryEnabled, enforcementEnabled, and insightsEnabled to false in the property set. The Shared Flows then pass requests through.

Troubleshooting

MCP Proxies

Send a test tools/list request to https://<host>/mcp/<server> with headers Content-Type: application/json and Accept: application/json, text/event-stream, and the body {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}.

Result Meaning
200 with the tool list The Shared Flow fetched the list, answered the client, and reported the tools to PlainID.
200 with error -32603 Upstream unavailable The Shared Flow couldn't reach the MCP server. Check that the server uses https:// with a public certificate authority and responds within 10 seconds.
200 with an empty tools list, enforcement on The PDP returned an error, or the clientSecret entry is missing.
404 ApplicationNotFound The proxy isn't deployed to the Environment that serves this host.

To trace a request, set debugEnabled to true and run an Apigee debug session on the proxy. Diagnostics appear in the stepExecution-stdout property of the JavaScript steps. For the steps, see the Debug section of the Apigee documentation.

Debug events for MCP: mcp_gate, mcp_pdp_request, mcp_pdp_response, mcp_decision, mcp_tools_list_upstream, mcp_discovery_payload, mcp_discovery_skip, mcp_discovery_too_big, mcp_filter, and mcp_error. Debug events for Insights: insights_payload, insights_skip, insights_too_big, and insights_error.

An SSL or handshake error on the collector call means the plainid-collector keystore has no alias named after the proxy, or the collector doesn't accept the certificate.

REST Proxies

Set debugPdpLogs to true and run an Apigee debug session. The Authorizer writes structured JSON lines to the stepExecution-stdout property of its JavaScript step. Client responses stay generic.

Notes

Authorize MCP and tools, and MCP dynamic discovery:

  • The Shared Flow answers tools/list itself. Proxy response policies and target settings (load balancing, custom TLS, timeouts) don't apply to tools/list. Use the DefaultFaultRule for response policies.
  • Enforcement covers tools/call and tools/list only. Other MCP methods pass through.
  • With enforcement on, any PDP error or timeout denies tools/call and returns an empty tools/list.
  • The Shared Flow doesn't send the agent identity to the PDP.
  • PDP requests include all request headers, including credentials such as Authorization and API keys.
  • A denied tools/call still counts against Quota policies in the proxy endpoint.
  • The Shared Flow doesn't support mTLS to the MCP server.
  • The Shared Flow doesn't discover tool lists over 10 MB.

Insights:

  • Insights doesn't report requests that the proxy endpoint rejects, for example through authentication or Quota.
  • Insights doesn't report request bodies over 10 MB.
  • Reports include credential headers and carry no user or agent identity.

© 2026 PlainID LTD. All rights reserved.