DEV Community: Anirbaan Chowdhury

Setting Up AgentGateway on SAP BTP Kyma

Anirbaan Chowdhury — Tue, 15 Sep 2026 15:04:51 +0000

A practical guide to deploying a production-grade MCP gateway — JWT authentication, CEL tool authorization, Istio mTLS, live backend registration, and Jaeger tracing — with the lessons that cost us the most time.

What this is

AgentGateway is an open-source, AI-first data plane that provides connectivity for agents, tools, and models in any environment. It handles agent-to-agent (A2A) communication, Model Context Protocol (MCP) tool serving, REST APIs exposed as agent-native tools, and AI routing to cloud and local LLMs (including the Gateway API Inference Extension). Across all of these it adds what the underlying protocols deliberately leave out: identity verification, fine-grained authorization, observability, and centralized routing.

This guide focuses on one of those use cases: running AgentGateway as an MCP gateway — in front of a fleet of MCP servers — and making it a genuinely enforced control point rather than an advisory one. The same infrastructure (Istio mTLS, XSUAA JWT auth, CEL authorization) applies to the other backend types, but everything below is written around MCP.

On SAP BTP, the natural runtime for this is Kyma — SAP's managed Kubernetes + Istio environment. Kyma gives you something most gateway setups don't: the ability to make the gateway genuinely enforced rather than advisory. Backend MCP servers get no public route. They exist only as ClusterIP Services. There is no hostname to call from outside the cluster, and inside the cluster an AuthorizationPolicy means only the gateway's workload identity can reach them. On Cloud Foundry, where every inter-app call goes over a public internet URL, we proved you could walk around the gateway entirely with a direct unauthenticated POST. On Kyma, there is no back door to walk around.

That's the architectural win this setup is designed to deliver. Here's how to build it.

What you'll end up with

A running deployment where:

MCP backends are ClusterIP-only — no external hostname exists; bypass is structurally impossible
The AgentGateway proxy validates XSUAA JWT tokens on every inbound request
A CEL expression on each backend strips tools from tools/list unless the token carries the right scope
Adding a new MCP server is kubectl apply of two manifests — no restart, no UI interaction
All intra-cluster traffic is Istio mTLS (STRICT namespace-wide) with an AuthorizationPolicy that whitelists only the proxy's SPIFFE identity to reach backends
Tool calls appear in structured access logs and as spans in Jaeger

                 ┌─────────────────────────────────────────────────────────┐
   MCP client    │  XSUAA (BTP service)                                     │
   (curl /       │  • issues client_credentials token                       │
   Inspector) ──▶│  • serves JWKS at /token_keys (HTTPS)                    │
        │        └─────────────────────────────────────────────────────────┘
        │ 1. get token                            ▲ 3. fetch JWKS (HTTPS)
        │ 2. call /mcp with Bearer                │
        ▼                                         │
 ┌───────────────┐   plaintext    ┌───────────────────────────────┐
 │ K8s Load-     │──────HTTP─────▶│  agentgateway-proxy   (2/2)   │
 │ Balancer Svc  │  (PERMISSIVE   │  agentgateway + Envoy sidecar │
 └───────────────┘   inbound)     │  • validates JWT (XSUAA)      │
                                  │  • CEL tool authorization     │
                                  └──┬───────────┬─────────┬──────┘
              xDS gRPC :9978          │           │ Istio   │ OTLP
              (DNS-verified TLS,      │           │ mTLS    │ gRPC
              sidecar excluded)       │           │ STRICT  │ :4317
                                      ▼           ▼         ▼
                          ┌────────────────┐ ┌──────────┐ ┌───────────┐
                          │ agentgateway   │ │ utility  │ │ jaeger-   │
                          │ control plane  │ │ -mcp 2/2 │ │ collector │
                          │  (1/1, NO      │ ├──────────┤ └─────┬─────┘
                          │   sidecar)     │ │ time-mcp │       │
                          └────────────────┘ │ 2/2      │       ▼
                                              └──────────┘ ┌──────────┐
                          AuthorizationPolicy: backends     │ jaeger   │
                          accept ONLY the proxy's SPIFFE   │ query UI │
                          identity, over mTLS              │(HTTPRoute│
                                                            └──────────┘

Everything except the proxy's LoadBalancer and the Jaeger UI HTTPRoute is ClusterIP. No other external addresses.

Kyma Gateway API note: AgentGateway installs its own GatewayClass named agentgateway. Kyma's own API Gateway module (kyma-system/kyma-gateway) is a separate implementation and is not required here. Both can coexist in the same cluster without conflict — each Gateway resource references its own gatewayClassName.

Prerequisites

Kyma environment enabled on your subaccount; kubeconfig downloaded and kubectl context set
Kyma modules enabled: Istio, SAP BTP Operator (services.cloud.sap.com/v1). The Kyma API Gateway module is not required.
helm CLI
Container registry reachable from the cluster for your MCP backend images. AgentGateway's own images pull from cr.agentgateway.dev — verify it's reachable:

STATUS=$(curl -o /dev/null -s -w "%{http_code}" https://cr.agentgateway.dev/v2/)
[[ "$STATUS" =~ ^(200|401)$ ]] && echo "reachable (HTTP $STATUS)" || echo "UNREACHABLE — check egress allowlist"

A 401 is normal — it's the OCI registry's auth challenge. Both 200 and 401 mean the registry is reachable.

How AgentGateway works on Kubernetes

There is no config.yaml and the Admin UI is read-only — it mirrors the control plane's xDS state for debugging. You cannot add backends or toggle policies through the UI. Every change is a kubectl apply. The control plane watches standard Kubernetes and Gateway API resources and pushes configuration to the data plane over xDS:

Resource	Purpose
`AgentgatewayBackend` (CRD)	MCP target registration — where is the server, what protocol
`AgentgatewayPolicy` (CRD)	Auth, authz, tracing, access-log configuration
`HTTPRoute` (Gateway API)	Routing rules — which path goes to which backend
`Gateway` (Gateway API)	Listener definition — AgentGateway's Deployer auto-creates the proxy Deployment and LoadBalancer Service

"Live-add an MCP server" means: apply a Deployment + Service, then apply an updated AgentgatewayBackend with the new target added. The control plane reconciles over xDS immediately. No restart, no UI interaction.

![AgentGateway Admin UI, Gateway Overview — a read-only banner reads "Configuration is managed by XDS. This view reflects the active runtime dump; editing is disabled." with counts of active Listeners, Routes, and Policies.]

The Admin UI in read-only mode: "Configuration is managed by XDS. This view reflects the active runtime dump; editing is disabled." It surfaces the live Listeners, Routes, and Policies (plus a CEL Playground for testing expressions) — but you can't add or change anything here. Every change is a kubectl apply.

Step 1 — Install AgentGateway

Label the namespace before creating any pods, so Istio injects sidecars from the start:

kubectl create namespace agentgateway-system
kubectl label namespace agentgateway-system istio-injection=enabled

Install the CRDs (includes Gateway API CRDs), then the control plane:

helm upgrade -i agentgateway-crds \
  oci://cr.agentgateway.dev/charts/agentgateway-crds \
  --version 0.0.0-latest-dev \
  -n agentgateway-system

helm upgrade -i agentgateway \
  oci://cr.agentgateway.dev/charts/agentgateway \
  --version 0.0.0-latest-dev \
  -n agentgateway-system

Then apply a GatewayClass (name: agentgateway) and a Gateway resource. The Deployer watches the Gateway and auto-creates the proxy Deployment and LoadBalancer Service.

Exit criteria — don't proceed until all three hold:

kubectl get gatewayclass agentgateway         # ACCEPTED: True
kubectl get gateway -n agentgateway-system    # PROGRAMMED: True
kubectl get svc -n agentgateway-system        # LoadBalancer IP/hostname assigned

Step 2 — The Istio sidecar split (the most important thing to get right)

This is the architecture decision that everything else depends on. You need three different sidecar configurations for three different workload roles:

Control plane — no sidecar at all (1/1)

AgentGateway's control plane must be sidecar-free. The proxy connects to it over gRPC TLS on port 9978 using standard DNS hostname verification. If Istio injects a sidecar, it intercepts that port and presents a SPIFFE cert (URI SAN only, no DNS SAN). The proxy's TLS client fails the handshake. Annotate the control plane deployment's pod template with sidecar.istio.io/inject: "false" so Istio skips it entirely.

On the proxy side, exclude port 9978 from Envoy's outbound interception:

# AgentgatewayParameters (applied to the agentgateway-proxy gateway)
spec:
  deployment:
    spec:
      template:
        metadata:
          annotations:
            traffic.sidecar.istio.io/excludeOutboundPorts: "9978"

Proxy — sidecar present, inbound PERMISSIVE (2/2)

The proxy needs an Envoy sidecar so it can originate mTLS toward the backends. The sidecar transparently upgrades the proxy's outbound plain HTTP to Istio mutual TLS — no backend TLS config needed anywhere.

The proxy's inbound traffic comes from the external LoadBalancer over plain HTTP (from real MCP clients). STRICT mode would reject this. Scope a workload-level PeerAuthentication: PERMISSIVE to the proxy only:

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: agentgateway-proxy-permissive
  namespace: agentgateway-system
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: agentgateway-proxy
  mtls:
    mode: PERMISSIVE

Backends — sidecar present, STRICT (2/2)

All MCP backend pods get a normal sidecar and stay under the namespace-wide STRICT policy. Their inbound only ever comes from the proxy's Envoy (mTLS) and they should never accept anything else.

The asymmetry is intentional and load-bearing: control plane: 1/1 sidecar-free; proxy: 2/2 with PERMISSIVE inbound; backends: 2/2 with STRICT.

Step 3 — Lock down the mesh

Apply a namespace-wide STRICT PeerAuthentication and an AuthorizationPolicy that restricts backend access to the proxy's SPIFFE identity:

# PeerAuthentication — namespace-wide STRICT
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: agentgateway-system
spec:
  mtls:
    mode: STRICT

# AuthorizationPolicy — only the proxy's service account reaches backends
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: backends-gateway-only
  namespace: agentgateway-system
spec:
  selector:
    matchLabels:
      role: mcp-backend     # applied to all backend pods via this label
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - "cluster.local/ns/agentgateway-system/sa/agentgateway-proxy"

Every backend pod must carry role: mcp-backend in its template labels for this selector to pick it up.

Step 4 — Deploy MCP backends (ClusterIP only)

Deploy each MCP server with a ClusterIP Service — no type: LoadBalancer, no Ingress, no external hostname. The backend literally cannot be reached from outside the cluster.

apiVersion: v1
kind: Service
metadata:
  name: poc-utility-mcp
  namespace: agentgateway-system
spec:
  selector:
    app: poc-utility-mcp
  ports:
    - port: 8080
      targetPort: 8080
  # no type: LoadBalancer — ClusterIP is the default and what we want

apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: all-mcp
  namespace: agentgateway-system
spec:
  mcp:
    targets:
      - name: utility
        static:
          host: poc-utility-mcp.agentgateway-system.svc.cluster.local
          port: 8080
          protocol: StreamableHTTP
      - name: time
        static:
          host: poc-time-mcp.agentgateway-system.svc.cluster.local
          port: 8080
          protocol: StreamableHTTP

Critical: all targets must be in one AgentgatewayBackend, not separate ones. If you create two AgentgatewayBackend resources with two HTTPRoute resources both matching /mcp, the proxy routes all traffic to only one — the other backend's tools never appear in tools/list. The same problem occurs with multiple backendRefs in a single HTTPRoute rule. One backend CRD, one HTTPRoute. Tool names are automatically prefixed with the target name (utility_uuid_generate, time_time_current) to avoid collisions.

Step 5 — XSUAA JWT authentication

Create the XSUAA service instance and binding via BTP Operator. The instance definition needs to grant the custom scope to the app's own OAuth client — otherwise a client_credentials token carries only uaa.resource and every tool gets stripped:

apiVersion: services.cloud.sap.com/v1
kind: ServiceInstance
metadata:
  name: poc-agentgateway-xsuaa
  namespace: agentgateway-system
spec:
  serviceOfferingName: xsuaa
  servicePlanName: application
  parameters:
    xsappname: poc-agentgateway
    tenant-mode: dedicated
    scopes:
      - name: "$XSAPPNAME.mcp.utility"
        description: "Access to utility MCP tools"
    authorities:
      - "$XSAPPNAME.mcp.utility"   # grant to own OAuth client — required

Once the binding is Ready, extract the values for the auth policy:

XSUAA_URL=$(kubectl get secret poc-agentgateway-xsuaa -n agentgateway-system \
  -o jsonpath='{.data.url}' | base64 -d)
CLIENT_ID=$(kubectl get secret poc-agentgateway-xsuaa -n agentgateway-system \
  -o jsonpath='{.data.clientid}' | base64 -d)

Configure JWT authentication on the Gateway:

traffic:
  jwtAuthentication:
    mode: Strict
    providers:
      - issuer: "<XSUAA_URL>/oauth/token"   # note: /oauth/token suffix required
        audiences:
          - "<CLIENT_ID>"                    # the sb-poc-agentgateway!t… value
        jwks:
          remote:
            url: "<XSUAA_URL>/token_keys"   # explicit https:// — use url, not backendRef

Set mode: Permissive initially (returns tools even without a token) to verify the backend wiring, then switch to Strict once routing is confirmed working.

Step 6 — CEL tool authorization

Apply an AgentgatewayPolicy targeting your AgentgatewayBackend:

apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: mcp-tool-authz
  namespace: agentgateway-system
spec:
  targetRefs:
    - group: agentgateway.dev
      kind: AgentgatewayBackend
      name: all-mcp
  backend:
    mcp:
      authorization:
        action: Allow
        policy:
          matchExpressions:
            - 'jwt.scope.exists(s, s.endsWith(".mcp.utility"))'

The endsWith pattern is deliberate: XSUAA prefixes scopes with the full application ID including a subaccount tenant index — e.g. poc-agentgateway!t123456.mcp.utility rather than the bare poc-agentgateway.mcp.utility. Matching literally on the full name will break across subaccounts. Matching by suffix works everywhere.

Step 7 — Access logs and Jaeger tracing

Enable structured access logging for MCP calls:

spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agentgateway-proxy
  frontend:
    accessLog:
      # Only log the interesting lines: actual tool calls, plus non-MCP requests.
      filter: 'mcp.methodName == "tools/call" || !has(mcp.methodName)'
      attributes:
        add:
          - name: tool_args
            expression: mcp.tool.arguments
          - name: tool_result
            expression: mcp.tool.result
          - name: tool_error
            expression: mcp.tool.error

For Jaeger, deploy it as a single Deployment with a multi-port ClusterIP Service (ports 4317 for OTLP gRPC, 16686 for the query UI). Then configure the tracing policy using url — not backendRef:

spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agentgateway-proxy
  frontend:
    tracing:
      url: "http://jaeger-collector.agentgateway-system.svc.cluster.local:4317"
      protocol: GRPC
      randomSampling: "true"

The reason url is required is explained in the lessons section. Point the Jaeger UI to an HTTPRoute at a path like /jaeger with a URL-rewrite filter.

![Jaeger UI showing 5 traces for the agentgateway service — tools/call, tools/list, initialize, and GET /mcp/* — each with span count, duration, and timestamp.]

AgentGateway emits a named span per MCP method. Every tools/call, tools/list, and initialize appears as a distinct trace. Click into any trace to see the full span waterfall with `gen_ai.` attributes.*

Live backend registration

Once everything is running, adding a new MCP server is two kubectl apply calls:

# Apply the new server's Deployment + ClusterIP Service
kubectl apply -f k8s/70-time-mcp.yaml

# Apply the updated all-mcp backend with the new target added
kubectl apply -f k8s/71-time-backend.yaml

The control plane sees the updated AgentgatewayBackend CRD and pushes the new xDS configuration to the proxy over the 9978 channel. The new server's tools appear in tools/list within seconds. Nothing restarts.

Isolation proof

The single most compelling moment in the demo is confirming the back door genuinely does not exist. From inside the cluster, with the wrong identity:

kubectl run probe --image=curlimages/curl --rm -it -n agentgateway-system -- \
  curl -s http://poc-utility-mcp.agentgateway-system.svc.cluster.local:8080/mcp
# → RBAC: access denied

![Terminal output showing RBAC: access denied when curling the backend ClusterIP directly from inside the cluster with the wrong workload identity.]

Correct in-cluster DNS name, correct port — still RBAC: access denied. The AuthorizationPolicy rejects any caller that isn't the proxy's SPIFFE identity.

From outside the cluster there is no poc-utility-mcp.<domain> to hit. That's the structural guarantee CF couldn't provide.

Lessons learned

These are the issues that cost real time during the initial setup. Each one has a non-obvious root cause. Reading this section before you start will save you hours.

1. The proxy won't go Ready — xDS TLS fails against its own control plane

Symptom: the proxy pod starts but never reaches the Ready state. Logs show UnknownIssuer or certificate not valid for name on the xDS gRPC channel.

Root cause: Istio injected a sidecar into the AgentGateway control plane (the namespace is istio-injection=enabled, so it injects into everything). That sidecar intercepts port 9978 and presents an Istio SPIFFE cert — URI SAN only, no DNS SAN. The proxy's xDS TLS client uses standard DNS hostname verification. The cert fails verification.

Fix: annotate the control plane deployment's pod template sidecar.istio.io/inject: "false", and exclude port 9978 from the proxy's outbound interception (traffic.sidecar.istio.io/excludeOutboundPorts: "9978", set via the proxy's AgentgatewayParameters). The proxy then reaches the control plane's own DNS-SAN cert and the handshake passes.

2. Every MCP call fails with `filter_chain_not_found`

Symptom: proxy is Ready, initialize returns Connection reset by peer, the backend's Envoy sidecar logs NR (no route) and filter_chain_not_found. The backend process never sees the request.

Root cause: the cluster has a STRICT PeerAuthentication (common on Kyma — the mesh policy may pre-date your deployment). The proxy was sending plain HTTP; STRICT means the backend's inbound listener has no plaintext filter chain. Connection refused before it reaches the app.

Dead end to avoid: the obvious instinct is to configure the proxy's built-in mesh integration (spec.istio.enabled: true) so it originates mTLS natively. On a sidecar-mode cluster that only gives a plaintext egress, and the SPIFFE-based backend TLS requires a Workload API the sidecar-free proxy doesn't have. Don't go down this path.

Fix: give the proxy an Envoy sidecar. The sidecar transparently upgrades the proxy's outbound connections to Istio mTLS — no backend TLS config needed. The proxy's inbound (from the LoadBalancer, plain HTTP) needs a workload-level PeerAuthentication: PERMISSIVE so STRICT doesn't reject it. Backends stay STRICT. The sidecar split in Step 2 above encodes this directly.

3. JWKS fetch fails — AgentGateway sends plain HTTP to a TLS port

Symptom: proxy is ready and auth is enabled, but every token is rejected because the JWKS keyset never loads. Logs show a connection error fetching the JWKS endpoint.

Root cause: jwks.remote.backendRef pointing at an ExternalName K8s Service causes AgentGateway to construct http://<host>:443/token_keys — plain HTTP to a TLS port. XSUAA only speaks HTTPS.

Fix: use jwks.remote.url with an explicit https:// scheme. When the scheme is https, the proxy originates backend TLS automatically. backendRef + ExternalName is the wrong tool for this.

4. `Error(InvalidIssuer)` — the token's `iss` doesn't match

Symptom: JWKS loads, signature verifies, but every request still returns 401 authentication failure … Error(InvalidIssuer).

Root cause: the ServiceBinding url field is https://<host>. But an XSUAA token's iss claim is https://<host>/oauth/token. The strings must match exactly.

Fix: issuer: <xsuaa-url>/oauth/token. Note: reaching this error is progress — it proves the JWKS fetch and signature verification are already working.

5. `tools/list` returns empty even with a valid token

Symptom: auth passes (200 response), but tools/list returns [].

Two root causes can stack here:

Scope not in token: client_credentials tokens carry only what's explicitly granted to the OAuth client. If you define the scope in the ServiceInstance but omit authorities, the token carries only uaa.resource. Fix: add authorities: ["$XSAPPNAME.mcp.utility"] to the ServiceInstance parameters.
CEL rule matching the wrong string: XSUAA prefixes scopes with the full application ID including a tenant index: poc-agentgateway!t123456.mcp.utility. A literal match on poc-agentgateway.mcp.utility fails. Fix: jwt.scope.exists(s, s.endsWith(".mcp.utility")) — matches by suffix, works across subaccounts.

6. Multi-backend routing conflict — only one server's tools appear

Symptom: tools/list returns tools from one MCP server but not the other, even after both are deployed and registered.

Root cause: two AgentgatewayBackend resources each with their own HTTPRoute both matching PathPrefix: /mcp. Gateway API tie-breaking sends all requests to one backend. The same problem occurs with multiple backendRefs in a single HTTPRoute rule — the proxy still routes to only the first.

Fix: put all MCP targets in a single AgentgatewayBackend under spec.mcp.targets[], with one HTTPRoute pointing to it. AgentGateway aggregates tools/list across all targets in the same backend. Tool names get prefixed with the target name to prevent collisions (utility_uuid_generate, time_time_current).

7. Jaeger OTLP export fails — connection reset

Symptom: traces never appear in Jaeger. Proxy Envoy logs show upstream_cluster: "PassthroughCluster" and response_flags: "UR" (upstream reset) on port 4317.

Root cause: AgentgatewayPolicy.spec.frontend.tracing.backendRef causes AgentGateway to resolve the K8s Service to pod IPs via the Endpoints API (standard Gateway API load-balancing behavior). When Envoy intercepts an outbound connection to a pod IP — not a ClusterIP — it has no named service cluster to match it against. It falls back to PassthroughCluster (plain TCP, no mTLS). Under STRICT PeerAuthentication, Jaeger's inbound Envoy has no plaintext filter chain: filter_chain_not_found, connection reset.

MCP backends work correctly because their AgentgatewayBackend.spec.mcp.targets[].static.host is set to the DNS hostname. AgentGateway connects by hostname → Envoy resolves to ClusterIP → matches the outbound|8080||... mTLS cluster → TLS handshake succeeds.

Fix: use url instead of backendRef in the tracing policy. url: "http://jaeger-collector.agentgateway-system.svc.cluster.local:4317" makes AgentGateway pass the DNS name to the TCP connection. Envoy resolves it to the ClusterIP and routes through the proper outbound|4317||jaeger-collector... mTLS cluster. response_code changes from reset to 200.

8. Jaeger UI returns 503 via the gateway HTTPRoute

Symptom: GET /jaeger/ returns 503 from the proxy with Connection reset by peer.

Root cause: same PassthroughCluster mechanism as lesson 7, but for port 16686. The HTTPRoute's backendRef resolves to the Jaeger pod IP, Envoy uses PassthroughCluster, Jaeger's inbound Envoy finds no plaintext filter chain under STRICT. Unlike the OTLP case, HTTPRoute has no url alternative in the Gateway API spec — you can't avoid the backendRef here.

Fix: add a workload-scoped PeerAuthentication: PERMISSIVE for Jaeger, overriding the namespace-wide STRICT only for the Jaeger pod:

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: jaeger-permissive
  namespace: agentgateway-system
spec:
  selector:
    matchLabels:
      app: jaeger
  mtls:
    mode: PERMISSIVE

This adds a plaintext filter chain alongside the mTLS one on Jaeger's inbound. The proxy's PassthroughCluster connection is accepted. All other workloads remain STRICT. The OTLP export (now using the correct mTLS path via url) is unaffected.

What the result demonstrates

Once everything above is in place, you can walk through these in order to show the system working:

Baseline — tools/list without a token returns all tools (auth in Permissive mode)
Isolation — curl from a random pod inside the cluster to a backend's ClusterIP gets RBAC: access denied
Live add — deploy a second MCP server with two kubectl applys; new tools appear in tools/list within seconds, nothing restarts
Auth on — apply the Strict auth policy; requests without a token return 401, requests with a valid token return tools
Scope authz — with the CEL rule applied, a token carrying *.mcp.utility sees the utility tools; a token without that scope gets []
Traces — tool calls appear as spans in Jaeger's UI with operation names like tools/call utility_uuid_generate; access logs on the proxy carry tool_args, tool_result, and tool_error for each tools/call

Key things to remember

The sidecar split is load-bearing. Control plane sidecar-free, proxy with sidecar + PERMISSIVE inbound, backends with sidecar + STRICT. Getting this wrong is the most common source of connectivity failures.
One AgentgatewayBackend, all targets. Separate backends with separate HTTPRoutes at the same path means only one backend wins. Consolidate under spec.mcp.targets[].
XSUAA scopes have a tenant suffix. $XSAPPNAME.mcp.utility becomes poc-agentgateway!t123456.mcp.utility in a real token. Match with endsWith, not literal equality.
Use url, not backendRef, for OTLP tracing. backendRef resolves to pod IPs, which Envoy routes through PassthroughCluster (no mTLS). url with a DNS hostname goes through the correct mTLS outbound cluster.
The Admin UI is read-only. It's a debug view of the xDS-pushed state. Changes are kubectl apply.

Principal Propagation with an MCP Server on SAP BTP — End to End

Anirbaan Chowdhury — Sun, 06 Sep 2026 15:57:20 +0000

If you have been building AI agents on top of SAP BTP, you have probably hit this wall: your agent calls a backend REST API and every request lands in the ABAP system under a single shared service account. Audit logs record the service account, not the person behind the request, and ABAP cannot enforce per-user authorization when every call arrives under the same identity.

The fix is principal propagation — a chain of trust that flows the end user's identity from their browser session all the way through BTP Cloud Foundry, the Cloud Connector, and into the ABAP ICM layer, where a short-lived X.509 certificate establishes who is actually making the call.

This post walks through how to build exactly that, with an MCP server (a Model Context Protocol server — a lightweight HTTP service that exposes typed tools an LLM agent can call) as the entry point so your LLM agent can call ABAP REST APIs as the authenticated user.

Why Not Just Use a Service Account?

You could skip all of this and use a single ABAP technical user. It is simpler to set up. But:

ABAP authorization objects are designed around individual users. A shared account means every call runs under the same permissions — you cannot enforce different rights for different people.
Audit logs (SM20, SAL) record the technical user, not the person who made the request. This makes incident investigation and compliance reporting much harder.
If an agent misbehaves or gets compromised, the blast radius is the full permissions of that service account.

Principal propagation gives you per-user authorization enforcement and full auditability at the ABAP layer, without requiring the cloud application to manage any ABAP credentials.

What We Are Building

The scope of this post is the MCP server and its principal propagation chain — everything from the MCP server down to ABAP. The browser login through the approuter to a user JWT (the top block below) is assumed to already be in place.

User browser
   │  authorization_code login
   ▼
Approuter (SAP BTP CF)   ──►  XSUAA  ──►  issues user JWT   ← assumed (not covered here)
   │
   │  user JWT (Bearer token)
   ▼
MCP Server (SAP BTP CF)                                     ← this post
   │  reads Connectivity service bindings from VCAP_SERVICES
   │  sends:  SAP-Connectivity-Authentication: Bearer <user JWT>
   │          Proxy-Authorization: Bearer <connectivity client_credentials token>
   ▼
BTP Connectivity Proxy
   │  tunnels over established WebSocket channel
   ▼
Cloud Connector
   │  verifies JWT signature (XSUAA public key, synced from BTP trust config)
   │  extracts user_uuid → generates short-lived X.509 cert  CN=<user>
   │  opens mTLS connection to ABAP; forwards cert in SSL_CLIENT_CERT header
   ▼
ABAP ICM  (trusts the Cloud Connector as reverse proxy)
   │  validates SSL_CLIENT_CERT → looks up CN=<user> in EXTID_DN
   ▼
ABAP business logic  ←─ executes as the real end user

Every hop in this chain preserves the end user's identity. Only the user JWT crosses the cloud/on-premise boundary; the two client_credentials tokens are consumed entirely within BTP.

Prerequisites

Component	Role
BTP subaccount (CF-enabled)	Hosts the apps and service instances
XSUAA service instance	Issues user JWTs via `authorization_code` flow
Connectivity service instance	Manages the Cloud Connector tunnel
Cloud Connector	On-premise agent that bridges BTP to the ABAP system
SAP ABAP system with REST APIs	Your backend

Step 1 — Set Up the BTP Services

You need one service instance bound to the MCP server. The approuter has its own XSUAA binding (not covered here). In your manifest.yml:

# manifest.yml
applications:
  - name: my-abap-mcp-server
    memory: 512M
    buildpacks:
      - python_buildpack
    command: python mcp_server.py
    services:
      - my-connectivity-service

The XSUAA instance (my-xsuaa) is bound to the approuter, not this app — the approuter handles login and issues the user JWT that the MCP server consumes. The MCP server never verifies JWT signatures itself; it delegates that responsibility to the Cloud Connector.

Create the instances via the BTP cockpit or CLI:

cf create-service connectivity lite my-connectivity-service

Step 2 — Configure the Cloud Connector

In your Cloud Connector administration UI:

2a. Register your BTP subaccount
Under Cloud To On-Premise → Add Subaccount. You will need your subaccount's XSUAA URL and your CF API endpoint. After registration the CC establishes a persistent WebSocket tunnel.

2b. Add the ABAP system as an accessible resource
Under Cloud To On-Premise → Access Control:

Back-end type: ABAP
Protocol: HTTP
Internal host/port: your real ABAP hostname and port
Virtual host: abap-backend-virtual (must match the destination URL)
Principal type: X.509 Certificate (General Usage)

2c. Configure the subject pattern
Under the system's "Principal Propagation" settings:

Subject pattern: CN=${user_uuid} (maps the user_uuid JWT claim to the cert CN)

The user_uuid claim in a standard XSUAA JWT is a UUID (e.g. 8f3a1b2c-4d5e-6789-abcd-ef0123456789). Inspect a decoded token from your own environment to confirm the exact value — this is what gets embedded as the cert CN and what you must map in EXTID_DN.

Step 3 — The MCP Server

This is the heart of the setup: a Python MCP server deployed to BTP CF that binds the Connectivity service, checks the caller's JWT zone ID, and routes each tool invocation through the connectivity proxy with the user's identity attached.

Why HTTP transport? MCP's stdio transport cannot carry per-request user identity — a single process handles all calls and there is no request-level header. The streamable-http transport gives each tool invocation its own HTTP request, so the caller can set Authorization: Bearer <user_jwt> and the server can validate and thread it through to the ABAP call.

The server uses Starlette middleware to check the JWT zone ID before any tool handler runs, storing the token in a contextvar so tool functions stay signature-clean — the LLM never sees a user_token parameter.

# requirements.txt
mcp[cli]==1.9.4
cfenv==0.5.3
requests==2.32.3
uvicorn==0.34.3
starlette==0.46.2

# mcp_server.py
import os
import base64
import json
import contextvars
import requests
from urllib.parse import quote
from cfenv import AppEnv
from mcp.server.fastmcp import FastMCP
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import JSONResponse

# ── BTP service bindings (injected by CF via VCAP_SERVICES) ──────────────────
env   = AppEnv()
_conn = env.get_service(name='my-connectivity-service')

XSUAA_ZONE_ID = '<your-btp-subaccount-zone-id>'   # BTP cockpit → subaccount → Overview → ID
ABAP_BASE     = 'http://abap-backend-virtual:<port>/sap/rest'

# ── per-request user JWT, threaded via contextvar ─────────────────────────────
_user_jwt: contextvars.ContextVar[str] = contextvars.ContextVar('user_jwt')


# ── token helper ──────────────────────────────────────────────────────────────

def _connectivity_token() -> str:
    c = _conn.credentials
    r = requests.post(
        f"{c['token_service_url']}/oauth/token",
        data={'grant_type': 'client_credentials',
              'client_id': c['clientid'], 'client_secret': c['clientsecret']},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()['access_token']


# ── JWT validation ────────────────────────────────────────────────────────────

def _decode_jwt(token: str) -> dict:
    segment = token.split('.')[1]
    segment += '=' * (-len(segment) % 4)
    return json.loads(base64.urlsafe_b64decode(segment))

def _validate_jwt(token: str) -> None:
    """Lightweight zone-ID check. Cryptographic signature verification is done by the CC."""
    claims = _decode_jwt(token)
    if claims.get('zid') != XSUAA_ZONE_ID:
        raise ValueError(f"Token zone {claims.get('zid')!r} does not match this subaccount")


# ── ABAP call via BTP connectivity proxy ─────────────────────────────────────

def _abap(method: str, path: str, **kwargs) -> requests.Response:
    user_jwt = _user_jwt.get()
    c   = _conn.credentials
    prx = f"http://{c['onpremise_proxy_host']}:{c['onpremise_proxy_port']}"
    url = f"{ABAP_BASE}/{path.lstrip('/')}"

    hdrs = {
        'SAP-Connectivity-Authentication': f'Bearer {user_jwt}',             # CC extracts identity from this JWT
        'Proxy-Authorization':             f'Bearer {_connectivity_token()}',  # app auth to the connectivity proxy
        'Accept': 'application/json',
    }

    r = requests.request(method.upper(), url, headers=hdrs,
                         proxies={'http': prx}, timeout=30, **kwargs)
    r.raise_for_status()
    return r


# ── middleware: validate JWT before every MCP request ─────────────────────────

class JWTMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        auth = request.headers.get('authorization', '')
        if not auth.startswith('Bearer '):
            return JSONResponse({'error': 'Authorization: Bearer header required'}, status_code=401)
        token = auth[7:]
        try:
            _validate_jwt(token)
        except Exception as exc:
            return JSONResponse({'error': str(exc)}, status_code=401)

        tok = _user_jwt.set(token)
        try:
            return await call_next(request)
        finally:
            _user_jwt.reset(tok)


# ── MCP tool definitions ───────────────────────────────────────────────────────

mcp = FastMCP('abap-tools', stateless_http=True)

@mcp.tool()
def list_orders(customer_id: str) -> list[dict]:
    """Return open orders for a customer. Runs in ABAP under the calling user's identity."""
    return _abap('GET', 'orders', params={'customerId': customer_id}).json()

@mcp.tool()
def get_order(order_id: str) -> dict:
    """Return details and line items for a single order."""
    return _abap('GET', f'orders/{quote(order_id, safe="")}').json()

@mcp.tool()
def update_order_status(order_id: str, status: str) -> dict:
    """Update an order's processing status. The ABAP system enforces the calling user's auth objects."""
    return _abap('POST', f'orders/{quote(order_id, safe="")}/status', json={'status': status}).json()


# ── entry point ───────────────────────────────────────────────────────────────

app = JWTMiddleware(mcp.streamable_http_app())

if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, host='0.0.0.0', port=int(os.environ.get('PORT', 8000)))

A few things worth calling out:

Two tokens, two purposes. The user JWT carries identity and is the only token that crosses the cloud/on-premise boundary. The connectivity client_credentials token authenticates the CF app to the connectivity proxy (it never leaves BTP). No Destination service is involved — the virtual hostname and port are configured directly in the Cloud Connector and hardcoded in ABAP_BASE.

SAP-Connectivity-Authentication is the magic header. The BTP connectivity proxy reads this header and passes it through the WebSocket tunnel to the Cloud Connector. The Cloud Connector's JWT validator decodes it, verifies the RS256 signature against the XSUAA public key, extracts user_uuid, and generates the per-user X.509 cert from that value.

The MCP server connects to the Connectivity Proxy over plain HTTP. The ABAP_BASE URL and proxy address both use http:// — there is no TLS at this hop. TLS and the mTLS handshake with the ABAP ICM are handled entirely by the Cloud Connector and Connectivity Proxy; the Python process is not part of those connections.

Zone ID validation is lightweight on purpose. The MCP server does not verify JWT signatures — that is the Cloud Connector's job and it does it cryptographically. The zid check is a fast guard against tokens from a completely different XSUAA tenant hitting this endpoint.

Token lifetime. XSUAA authorization_code JWTs are typically valid for 12 hours. Long agentic loops may outlive a token. The middleware does not check exp — expiry is enforced by the Cloud Connector when it verifies the JWT signature, causing the ABAP call to fail. Design your agent framework to handle auth failures and trigger a token refresh rather than retrying blindly.

Connecting an agent

Any MCP client that speaks streamable HTTP can consume this server — point it at the deployed route and pass the user's JWT as a bearer token. With LangChain's MCP adapter, for example:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "abap": {
        "transport": "streamable_http",
        "url": "https://my-abap-mcp-server.cfapps.<region>.hana.ondemand.com/mcp",
        "headers": {"Authorization": f"Bearer {user_jwt}"},
    }
})
tools = await client.get_tools()   # hand these to your agent / LLM

The key point: the Authorization header carries the end user's JWT, not a service credential. Every tool call the agent makes then executes in ABAP under that user's identity — which is the whole reason for the principal propagation chain.

Step 4 — ABAP Side Configuration

This is where most setups stall. Four things must all be in place.

4a. STRUST — Import the Cloud Connector's CA certificates

The ABAP system needs to trust two certificate authorities:

The CA that issued the Cloud Connector's System Certificate (e.g. SAPNetCA_G2). This is used for the mTLS handshake between the CC and the ABAP ICM.
The Cloud Connector's Local CA (CN=SCC-Local-CA). This is used to validate the short-lived per-user X.509 certs that the CC generates. Download this from your CC admin UI: Configuration → On Premise → CA Certificate → Download DER.

Import both into the SSL Server Standard PSE in transaction STRUST.

4b. RZ10 — Trust the Cloud Connector as a reverse proxy

By default, ABAP ICM strips any SSL_CLIENT_CERT header from incoming requests (a security measure). You must explicitly list the Cloud Connector as a trusted reverse proxy so ICM accepts the forwarded user cert.

In transaction RZ10, open the DEFAULT profile, Extended Maintenance, and add:

icm/trusted_reverse_proxy_0 = SUBJECT="CN=<your-cloud-connector-cn>, O=<org>, C=<country>", ISSUER="CN=<issuer-cn>, O=SAP, ..."

Use the exact Subject and Issuer from the CC's System Certificate. After saving, restart ICM via SMICM → Administration → ICM → Exit Hard → Global.

If you skip this step, the CC will generate the user cert correctly, forward it in SSL_CLIENT_CERT, and ABAP will silently discard it. The request will still reach ABAP but as an anonymous/default user — a subtle failure that is easy to miss.

4c. EXTID_DN — Map certificate subjects to SAP users

In transaction EXTID_DN (or via program RSUSREXT), add a mapping entry:

Field	Value
External ID Type	DN
External ID	`CN=<user_uuid value>`
User	SAP user account

For example, if your user_uuid is 8f3a1b2c-4d5e-6789-abcd-ef0123456789, the entry would be CN=8f3a1b2c-4d5e-6789-abcd-ef0123456789 → SAP user JDOE.

For production with many users, use CERTRULE to set up a pattern-based mapping rule (e.g. extract CN and map to the SAP user with the same ID) rather than maintaining individual entries.

4d. SICF — Enable certificate logon on the service

In transaction SICF, navigate to your REST API's ICF service node, open its properties, and verify that "Logon Through SSL Certificate" is enabled as an allowed logon method.

Verifying end to end

Call one of your MCP tools with a valid user JWT and then check SM20 (Security Audit Log) in the ABAP system. If the session shows the actual user — not a technical account — principal propagation is working. If it shows the wrong user or is anonymous, work through the debugging checklist below.

The Six Trust Boundaries in One Diagram

[BTP Subaccount]
     │
     │  1. WebSocket tunnel (registered CC)
     ▼
[Cloud Connector]
     │
     │  2. XSUAA public key (synced from BTP trust config)
     │     → verifies JWT signature
     │
     │  3. mTLS to ABAP ICM
     │     (CC presents System Cert; ABAP trusts its CA via STRUST)
     ▼
[ABAP ICM]
     │
     │  4. Trusted reverse proxy param (RZ10)
     │     → accepts SSL_CLIENT_CERT header from CC
     │
     │  5. Local CA in STRUST
     │     → validates the forwarded short-lived user cert
     │
     │  6. EXTID_DN / CERTRULE
     │     → maps CN=<user_uuid> to a SAP user account
     ▼
[ABAP business logic — executing as the real user]

All six must be in place. A failure at any boundary usually manifests as the request completing but the ABAP session belonging to the wrong user or failing authorization.

Debugging Checklist

Symptom	Likely cause
TLS handshake fails between CC and ABAP	CC's System Cert CA not in STRUST
Request reaches ABAP as anonymous user	`trusted_reverse_proxy` param missing, or ICM not restarted after RZ10 change
ABAP returns "unknown CA" on client cert	Cloud Connector's Local CA not imported in STRUST
SM20 shows "external ID not found"	No EXTID_DN entry for `CN=<user_uuid>`
403 after user appears to be logged in	Missing ABAP authorization objects for the propagated user
Cloud Connector log: "JWT cannot be verified"	XSUAA signing key not synced from BTP trust configuration
Cloud Connector log: "JWT cannot be verified" (intermittent)	CC key cache stale — trigger a manual trust sync in the CC admin UI
`401` from the MCP server	User JWT `zid` does not match the configured zone ID
`502` from the MCP server	Connectivity service credentials missing or proxy unreachable

Summary

The core flow is:

User logs in via XSUAA authorization_code flow → gets a JWT with user_uuid
LLM agent calls an MCP tool, forwarding the user JWT
MCP server on BTP CF routes the call through the connectivity proxy, setting SAP-Connectivity-Authentication: Bearer <user_jwt>
Cloud Connector verifies the JWT, extracts user_uuid, generates a short-lived X.509 cert CN=<user_uuid>
ABAP ICM receives the request with the user cert forwarded in SSL_CLIENT_CERT
ABAP maps the cert subject to a SAP user via EXTID_DN and runs the business logic as that user

The key insight is that identity is carried as a signed JWT token across the cloud layer, then converted to an X.509 certificate at the network boundary — a format ABAP's ICM already understands natively. The MCP server is just the latest entry point into an existing protocol.

This post is intended as guidance to illustrate how principal propagation works end to end. The code is simplified to keep the focus on the identity flow — a production deployment will need additional hardening (signature validation at the MCP layer, error handling, secrets management, logging, and so on). Treat it as a starting point, not a drop-in solution.

Teaching an LLM to pull MCP Resources and Prompts on demand (instead of drowning it in context)

Anirbaan Chowdhury — Sun, 30 Aug 2026 05:19:03 +0000

Teaching an LLM to pull MCP Resources and Prompts on demand (instead of drowning it in context)

How we wired the Model Context Protocol's "application-controlled" primitives into a model-controlled tool-calling loop — and why that small shift changes everything about context hygiene.

TL;DR

The Model Context Protocol (MCP) gives a server three ways to expose capability: tools, resources, and prompts. Tools drop straight into an LLM's function-calling loop. Resources and prompts don't — they're application-controlled, so most integrations just dump every resource's content into the system prompt and hope for the best.

That approach bloats context, truncates large documents, breaks on binary files, and gives the model zero say in what it actually needs.

Our fix: promote resources and prompts into synthetic, auto-approved LLM tools — read_resource(uri) and invoke_prompt(name). The system prompt now carries only a lightweight catalog (URIs + descriptions). The model reads a resource only when it decides it needs one, through the exact same tool-calling machinery it already uses. On-demand, selective, full-fidelity.

The three MCP primitives — and the control model nobody talks about

MCP defines three server capabilities, but the interesting part is who's in control of each:

Primitive	Who decides when it's used	Natural fit for tool-calling?
Tools	The model (it calls them)	✅ Yes — this is what function calling is
Resources	The application / user	❌ No native hook in the loop
Prompts	The user (usually a slash-command)	❌ No native hook in the loop

Tool calling is model-controlled by design: the LLM emits a tool_use block, you execute it, you feed the result back. Beautiful.

Resources and prompts are application-controlled. The spec's mental model is a human clicking "attach this file" or "/use this prompt template." There is no obvious place for them inside an autonomous agent's reasoning loop. So what do most integrations do?

The naive approach (and why it hurts)

The path of least resistance is to fetch every resource at startup and paste it into the system prompt:

## Available Resources
### Resource: SUM ABAP Test Matrix
URI: sap-btp://sum-abap-v1
Content:
<... 11,000 characters of markdown ...>
### Resource: API Docs
URI: sap-btp://api-docs
Content:
<... more ...>

Four problems show up fast:

Context bloat. Every request pays for every resource, whether or not it's relevant. Ten resources × a few thousand tokens each = a system prompt that dwarfs the actual conversation.
Truncation. To keep bloat sane, you cap content (content[:2000]) — and now large documents are silently chopped. In our case the SUM ABAP matrix lost its entire product list and output-format section below the 2,000-char line.
Binary breaks. A PDF or PNG resource has no meaningful text form. Naive extractors try blob.as_string(), hit a UnicodeDecodeError, and quietly emit "[No content available]".
No agency. The model can't say "I don't need any of these right now" or "give me that one, in full." It's force-fed.

The insight: make resources and prompts look like tools

Here's the shift. The LLM already has a clean, well-understood way to ask for something on demand: it calls a tool. So instead of fighting the control model, we translate it.

We register two DARA-internal tools that don't exist on any MCP server — they're synthesized client-side:

read_resource(uri) → fetches one resource's content when the model asks.
invoke_prompt(name) → injects a named prompt template into the conversation when the model asks.

The system prompt now advertises only a catalog — names, URIs, and descriptions, no content:

## Available Resources
The following resources can be read on demand. To read one, call the
`read_resource` tool with its exact URI. Do not assume a resource's
contents until you have read it.

### Resource: SUM ABAP Test Matrix
URI: sap-btp://sum-abap-v1
Description: SUM (Software Update Manager) test matrix specification for ABAP products

The model sees what exists, then reaches for exactly what it needs — through the tool loop it already speaks fluently.

Implementation walkthrough

We built this on top of LangGraph + langchain-mcp-adapters, but the pattern is framework-agnostic.

1. Synthesize the tool with a schema

read_resource is a StructuredTool with a one-field schema. Its func is a no-op lambda — we never actually run it as a function; we intercept it in the graph (see step 3).

from pydantic import BaseModel, Field
from langchain_core.tools import StructuredTool

class _ReadResourceArgs(BaseModel):
    uri: str = Field(description="The exact URI of the MCP resource to read, "
                                 "e.g. 'sap-btp://sum-abap-v1'.")

read_resource_tool = StructuredTool.from_function(
    func=lambda uri: "",                      # placeholder — handled in the graph
    name="read_resource",
    description=(
        "Read the full contents of an MCP resource by its URI. "
        "Call this when the user asks to read, open, or summarize a resource, "
        "or when you need a resource's contents to answer. "
        "Only resources listed under 'Available Resources' can be read."
    ),
    args_schema=_ReadResourceArgs,
)
tools = list(tools) + [read_resource_tool]
allowed_tools_without_review.append("read_resource")   # auto-approve, no human gate

Two things matter here:

The description is the UX. It's the only instruction the model gets on when to call this. Write it like a prompt, because it is one.
Auto-approval. In an agent with human-in-the-loop review, reading a read-only resource shouldn't require a click. We add it to the "no review" allow-list so the graph routes straight to execution.

2. Build a content map once, keyed by URI

We fetch resources once (the adapter already returns their content as Blob objects) and index them by URI so the on-demand read is an O(1) lookup — no second network round-trip:

resources_content = {}
for res in (resources or []):
    uri, name, description, content = _extract_resource_fields(res)
    # URIs can arrive as pydantic AnyUrl objects — normalize to str so the
    # plain-string URI the LLM passes actually matches the dict key. (Gotcha!)
    uri = str(uri) if uri is not None else ""
    if uri and uri != "unknown":
        resources_content[uri] = {"name": name, "content": content}

3. Intercept the tool call in the graph

When the model emits a read_resource call, we don't invoke a function — we look up the content and hand it back as a tool message. Because a tool result flows naturally back into the model's context, the content lands only when requested:

if tool_call["name"] == "read_resource":
    uri = str(tool_call["args"].get("uri", ""))
    res = resources_content.get(uri)
    if res:
        new_messages.append({
            "role": "tool",
            "name": "read_resource",
            "content": res["content"],          # full content, no truncation
            "tool_call_id": tool_call["id"],
        })
    else:
        available = list(resources_content.keys())
        new_messages.append({
            "role": "tool",
            "name": "read_resource",
            "content": f"Resource '{uri}' not found. Available URIs: {available}",
            "tool_call_id": tool_call["id"],
        })
    continue

The mirror image for prompts: invoke_prompt injects the template's messages as real Human/AI turns, which is exactly how the MCP spec intends prompts to be surfaced.

4. Handle binary honestly (don't decode bytes as text)

langchain-mcp-adapters collapses every resource into a Blob: text lands in .data as a str, binary as raw bytes, with the media type on the .mimetype attribute (not in metadata — a common trip-up). So we branch on the mime type instead of blindly calling .as_string():

def _is_text_mime(mime: str) -> bool:
    mime = (mime or "").lower().split(";")[0].strip()
    return (mime.startswith("text/")
            or mime.endswith(("+json", "+xml", "+yaml"))
            or mime in {"application/json", "application/xml", "application/yaml"})

# inside the extractor, for a Blob:
data = getattr(resource, "data", None)
if isinstance(data, bytes):
    if _is_text_mime(mime):
        return uri, name, description, data.decode("utf-8")
    # Binary (PDF, PNG, ...) → an honest descriptor, NOT raw bytes/base64
    return uri, name, description, (
        f"[Binary resource: {mime or 'application/octet-stream'}, "
        f"{_human_size(len(data))}. This is not text and cannot be inlined; "
        f"open it with a client that handles its media type.]"
    )

This is aligned with the MCP spec itself: binary payloads belong in typed media content blocks or are referenced by URI — never stuffed into a text field. A model reading [Binary resource: application/pdf, 240.0 KB] knows exactly what it's looking at and can decide what to do, instead of choking on garbage or getting a misleading "no content."

The flow, end to end

   ┌─────────────────┐
   │  User message   │
   └────────┬────────┘
            │
            ▼
   ┌──────────────────────────────────────────┐
   │ System prompt = resource CATALOG only     │
   │ (URIs + descriptions, NO content)         │
   └────────┬─────────────────────────────────┘
            │
            ▼
      ┌───────────────┐
      │  LLM decides  │
      └──┬─────────┬──┘
         │         │
 needs a │         │ doesn't need one
 resource│         └──────────────► Answer directly
         ▼
 ┌──────────────────────────┐
 │ tool_use: read_resource  │
 │        (uri)             │
 └────────────┬─────────────┘
              ▼
 ┌──────────────────────────────┐
 │ Graph intercepts the call     │
 │ (auto-approved, no HITL gate) │
 └────────────┬─────────────────┘
              ▼
 ┌──────────────────────────────┐
 │ Look up URI in content map    │
 └───────┬───────────────┬──────┘
         │ text          │ binary
         ▼               ▼
 ┌────────────────┐  ┌──────────────────────┐
 │ Full content   │  │ Descriptor:          │
 │ as tool message│  │ mime type + size     │
 └───────┬────────┘  └───────────┬──────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
              (back to LLM ──► answer)

Only the "needs a resource" branch ever pays the content cost — and it pays the full cost, untruncated, for just that resource.

Why this is nice

Token-efficient. The system prompt holds a catalog (tens of tokens per resource), not a library. Content enters context only on read.
Selective. The model — or the user, phrasing a request — decides what to load. Ten irrelevant resources cost almost nothing.
Full fidelity. No truncation cap needed, because you're no longer defending against ten simultaneous dumps. The one resource you asked for arrives whole.
Binary-safe. Mime-driven handling means PDFs and images degrade to a clear descriptor instead of a crash or a lie.
Spec-aligned. Application-controlled primitives stay application-controlled — we just expose an affordance for the model to request them, rather than pre-deciding on its behalf.
Uniform mental model. Resources, prompts, and real tools all flow through one loop. No special-case rendering paths, no bespoke context-stuffing logic.

Gotchas worth stealing

AnyUrl vs str. MCP resource URIs often surface as pydantic AnyUrl objects. If your content map is keyed by AnyUrl and the LLM passes a plain string, .get() silently misses. Normalize to str on both sides.
Mime lives on .mimetype, not metadata. For langchain-mcp-adapters Blobs, the media type is an attribute; metadata only carries the uri. Read the right field or every binary looks like application/octet-stream.
The tool description is the routing logic. There's no separate policy telling the model when to read a resource — only the tool's description. Invest in it.
Auto-approve read-only reads. If your agent has human review gates, forcing a click to read a read-only resource kills the UX. Allow-list it.
A no-op func is fine. The synthesized tool never executes as a function; the graph intercepts it. The lambda is just there to satisfy the schema.

Where it goes next

The binary branch is the single hook for richer handling: extract PDF text server-side, or emit an ImageContent block to a vision-capable model for images. Because everything already funnels through one read_resource path, adding a modality is a localized change — not a re-architecture.

The bigger takeaway: when a protocol primitive doesn't fit your execution model, don't force the model to swallow it up front. Give the model an affordance to ask, and let the loop it already understands do the rest.

Built on the Model Context Protocol (2025-03-26), LangGraph, and langchain-mcp-adapters. The pattern is framework-agnostic — anywhere you have tool-calling and MCP, you can do this.

DEV Community: Anirbaan Chowdhury

Setting Up AgentGateway on SAP BTP Kyma

What this is

What you'll end up with

Prerequisites

How AgentGateway works on Kubernetes

Step 1 — Install AgentGateway

Step 2 — The Istio sidecar split (the most important thing to get right)

Step 3 — Lock down the mesh

Step 4 — Deploy MCP backends (ClusterIP only)

Step 5 — XSUAA JWT authentication

Step 6 — CEL tool authorization

Step 7 — Access logs and Jaeger tracing

Live backend registration

Isolation proof

Lessons learned

1. The proxy won't go Ready — xDS TLS fails against its own control plane

2. Every MCP call fails with filter_chain_not_found

3. JWKS fetch fails — AgentGateway sends plain HTTP to a TLS port

4. Error(InvalidIssuer) — the token's iss doesn't match

5. tools/list returns empty even with a valid token

6. Multi-backend routing conflict — only one server's tools appear

7. Jaeger OTLP export fails — connection reset

8. Jaeger UI returns 503 via the gateway HTTPRoute

What the result demonstrates

Key things to remember

Principal Propagation with an MCP Server on SAP BTP — End to End

Why Not Just Use a Service Account?

What We Are Building

Prerequisites

Step 1 — Set Up the BTP Services

Step 2 — Configure the Cloud Connector

Step 3 — The MCP Server

Connecting an agent

Step 4 — ABAP Side Configuration

4a. STRUST — Import the Cloud Connector's CA certificates

4b. RZ10 — Trust the Cloud Connector as a reverse proxy

4c. EXTID_DN — Map certificate subjects to SAP users

4d. SICF — Enable certificate logon on the service

Verifying end to end

The Six Trust Boundaries in One Diagram

Debugging Checklist

Summary

Teaching an LLM to pull MCP Resources and Prompts on demand (instead of drowning it in context)

Teaching an LLM to pull MCP Resources and Prompts on demand (instead of drowning it in context)

TL;DR

The three MCP primitives — and the control model nobody talks about

The naive approach (and why it hurts)

The insight: make resources and prompts look like tools

Implementation walkthrough

1. Synthesize the tool with a schema

2. Build a content map once, keyed by URI

3. Intercept the tool call in the graph

4. Handle binary honestly (don't decode bytes as text)

The flow, end to end

Why this is nice

Gotchas worth stealing

Where it goes next

2. Every MCP call fails with `filter_chain_not_found`

4. `Error(InvalidIssuer)` — the token's `iss` doesn't match

5. `tools/list` returns empty even with a valid token