Backends

Configure upstream targets — MCP servers, A2A agents, HTTP services, and OpenAPI endpoints.

Backends define where agentgateway forwards matched traffic. They appear inside routes as inline configurations. agentgateway supports four backend types: mcp, host (plain HTTP/A2A), and named backend references defined at the top-level backends list.

Backend types

Each entry in routes[].backends must be exactly one of:

Field	Description
mcp	Connect to one or more MCP servers (stdio, HTTP/SSE, or OpenAPI).
ai	Proxy to an LLM provider (OpenAI, Gemini, Anthropic, Bedrock, Azure OpenAI, Vertex AI).
host	Plain HTTP hostname or A2A agent address.
aws	AWS-native backends such as AWS Bedrock AgentCore.
backend	Reference to a named backend in the top-level backends list.
service	Reference to a Kubernetes service (control-plane environments).

---

MCP backend

The mcp backend type proxies traffic to one or more MCP (Model Context Protocol) servers. Multiple targets are aggregated: the gateway exposes all tools, resources, and prompts as a single unified MCP server to clients.

When multiple targets are configured, each tool name is prefixed with <target-name>_ to avoid collisions between servers.

backends:
  - mcp:
      targets:
        - name: <target-name>
          # One of: stdio, sse, mcp, openapi

MCP target fields

mcp.targets[].name · string · required

A unique name for this MCP target. Used to prefix tool names when multiple targets are aggregated (e.g., weather_get_forecast).

mcp.targets[].policies · object

Per-target policies (header modification, backend TLS, authentication, etc.). These merge with and can override route-level policies for this specific target.

Stdio transport

Agentgateway spawns a local process and communicates over its standard input/output. Use this for MCP servers distributed as CLI tools.

mcp.targets[].stdio.cmd · string · required

The command to execute. The process is started when the first client connects.

mcp.targets[].stdio.args · string[]

Arguments to pass to the command.

mcp.targets[].stdio.env · object

Environment variables to set for the spawned process. Key-value string pairs.

single server (stdio)

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: everything
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: time
                      stdio:
                        cmd: uvx
                        args: ["mcp-server-time"]
                    - name: everything
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]

HTTP/SSE transport

Agentgateway connects to an already-running MCP server over HTTP. Two sub-types are supported:

SSE transport (sse) — connects to an MCP server using the legacy Server-Sent Events transport.

mcp.targets[].sse.host · string · required

Hostname or IP address of the MCP server.

mcp.targets[].sse.port · number

Port of the MCP server.

mcp.targets[].sse.path · string

URL path prefix, e.g. /sse.

Streamable HTTP transport (mcp) — connects to an MCP server using the modern streamable HTTP transport.

mcp.targets[].mcp.host · string · required

Hostname or IP address of the MCP server.

mcp.targets[].mcp.port · number

Port of the MCP server.

mcp.targets[].mcp.path · string

URL path prefix, e.g. /mcp.

backends:
  - mcp:
      targets:
        - name: remote-tools
          mcp:
            host: tools.internal
            port: 3001
            path: /mcp

OpenAPI transport

Agentgateway converts an OpenAPI specification into MCP tools, enabling any REST API to be used by AI agents over the MCP protocol.

mcp.targets[].openapi.host · string · required

Hostname of the REST API.

mcp.targets[].openapi.port · number

Port of the REST API.

mcp.targets[].openapi.path · string

Base path for the API.

mcp.targets[].openapi.schema · object · required

The OpenAPI schema to use. Provide either a file path or a url.

Show schema sources

openapi.schema.file · string

Local file path to the OpenAPI YAML or JSON specification.

openapi.schema.url · string

URL to fetch the OpenAPI specification from at startup.

backends:
  - mcp:
      targets:
        - name: petstore
          openapi:
            host: api.example.com
            port: 443
            path: /v3
            schema:
              url: https://api.example.com/v3/openapi.json

---

HTTP / A2A backend

Use host to forward traffic to any HTTP service or A2A (Agent-to-Agent) endpoint. This is the simplest backend type and requires only a hostname and optional port.

host · string · required

The upstream hostname or host:port address to forward requests to.

Examples: 127.0.0.1:8080, backend.internal:9000, localhost:9999.

plain HTTP

binds:
  - port: 3000
    listeners:
      - protocol: HTTP
        routes:
          - backends:
              - host: 127.0.0.1:8080

A2A traffic

For A2A (Agent-to-Agent protocol) traffic, use host combined with the a2a: {} route policy. The policy enables A2A-specific processing, telemetry, and tracing.

a2a/config.yaml

binds:
  - port: 3000
    listeners:
      - routes:
          - policies:
              cors:
                allowOrigins:
                  - "*"
                allowHeaders:
                  - content-type
              # Mark this route as A2A traffic
              a2a: {}
            backends:
              - host: localhost:9999

---

Top-level named backends

The top-level backends list defines named backend resources that can be referenced by routes using backend: <name>.

backends[].name · string · required

A unique name for this backend. Referenced from routes as backend: <name>.

backends[].host · string

The upstream hostname or host:port.

backends[].policies · object

Policies attached to this backend (TLS, auth, health, HTTP settings, etc.). These apply whenever this backend is referenced from any route.

backends:
  - name: api-backend
    host: api.internal:8080
    policies:
      backendTLS:
        root: /etc/certs/ca.crt
      backendAuth:
        key: "Bearer ${API_KEY}"

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - backend: api-backend

---

Backend TLS (backendTLS)

Configure TLS for connections agentgateway makes to the upstream backend.

policies.backendTLS · object

Send TLS to the backend.

Show backendTLS fields

backendTLS.cert · string

Path to the PEM client certificate for mTLS connections to the backend.

backendTLS.key · string

Path to the PEM private key for the client certificate.

backendTLS.root · string

Path to the PEM CA bundle used to verify the backend’s server certificate. When omitted, the system root CAs are used.

backendTLS.hostname · string

Override the SNI hostname used during TLS handshake. Defaults to the backend host.

backendTLS.insecure · boolean

Skip all TLS verification. Not recommended for production.

backendTLS.insecureHost · boolean

Skip hostname verification only. The certificate is still validated.

backendTLS.alpn · string[]

ALPN protocols to advertise during the TLS handshake, e.g. ["h2", "http/1.1"].

backendTLS.subjectAltNames · string[]

Acceptable Subject Alternative Names in the backend certificate. Overrides the default hostname check.

policies:
  backendTLS:
    root: /etc/certs/ca.crt
    hostname: api.internal

---

Backend auth (backendAuth)

Authenticate agentgateway to upstream services. Exactly one auth variant must be set.

passthrough — forward client credentials

Pass the incoming request’s Authorization header directly to the backend without modification.

policies:
  backendAuth:
    passthrough: {}

key — static API key or bearer token

Attach a static key as the Authorization header on every upstream request. The key value can be an inline string or loaded from a file.

inline key

policies:
  backendAuth:
    key: "Bearer sk-proj-abc123"

key from file

policies:
  backendAuth:
    key:
      file: /run/secrets/api-key

gcp — Google Cloud identity token

Obtain a GCP identity or access token from the instance metadata service (or a service account) and attach it to upstream requests.

policies:
  backendAuth:
    gcp:
      type: identityToken   # or accessToken
      audience: https://backend.example.com

• type — identityToken or accessToken.
• audience — Audience for the token. Defaults to the backend host when omitted.

aws — AWS SigV4 request signing

Sign upstream requests using AWS Signature Version 4.

policies:
  backendAuth:
    aws:
      accessKeyId: AKIAIOSFODNN7EXAMPLE
      secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      region: us-east-1
      sessionToken: optional-session-token

azure — Azure managed identity or service principal

Obtain an Azure access token and attach it to upstream requests. Supports explicit service principal credentials, managed identity, workload identity, and developer implicit credentials.

client secret (service principal)

policies:
  backendAuth:
    azure:
      explicitConfig:
        clientSecret:
          tenant_id: "<tenant-id>"
          client_id: "<client-id>"
          client_secret: "<client-secret>"

managed identity

policies:
  backendAuth:
    azure:
      explicitConfig:
        managedIdentity:
          userAssignedIdentity:
            clientId: "<client-id>"

workload identity

policies:
  backendAuth:
    azure:
      explicitConfig:
        workloadIdentity: {}

developer implicit (local dev)

policies:
  backendAuth:
    azure:
      developerImplicit: {}

---

Complete examples

MCP backend with API key auth and TLS

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: remote-api
                      mcp:
                        host: mcp.example.com
                        port: 443
                      policies:
                        backendTLS:
                          root: /etc/certs/ca.crt
                        backendAuth:
                          key: "Bearer sk-secret"

A2A backend with CORS

binds:
  - port: 3000
    listeners:
      - routes:
          - policies:
              cors:
                allowOrigins: ["*"]
                allowHeaders: ["content-type", "cache-control"]
              a2a: {}
            backends:
              - host: localhost:9999

OpenAPI backend

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: petstore
                      openapi:
                        host: petstore.swagger.io
                        port: 443
                        schema:
                          url: https://petstore.swagger.io/v2/swagger.json

---

AI backend

The ai backend proxies traffic to an LLM provider. It enables AI-specific policies like prompt guard and prompt enrichment, and exposes LLM-specific telemetry (token counts, model used, streaming status).

backends:
- ai:
    name: openai
    provider:
      openAI:
        model: gpt-4o-mini

Supported providers

OpenAI

backends:
- ai:
    name: openai
    provider:
      openAI:
        model: gpt-4o-mini

Authenticate using backendAuth.key set to your OPENAI_API_KEY environment variable:

policies:
  backendAuth:
    key: $OPENAI_API_KEY

Google Gemini

backends:
- ai:
    name: gemini
    provider:
      gemini:
        model: gemini-1.5-flash

Anthropic

backends:
- ai:
    name: anthropic
    provider:
      anthropic:
        model: claude-3-5-sonnet-20241022

Google Vertex AI

backends:
- ai:
    name: vertex
    provider:
      vertex:
        model: gemini-1.5-flash
        region: us-central1
        projectId: my-gcp-project

AWS Bedrock

backends:
- ai:
    name: bedrock
    provider:
      bedrock:
        model: anthropic.claude-3-5-sonnet-20241022-v2:0
        region: us-east-1

Azure OpenAI

backends:
- ai:
    name: azure-openai
    provider:
      azureOpenAI:
        model: gpt-4o
        host: https://my-resource.openai.azure.com
        apiVersion: "2024-02-01"

AI backend fields

ai.name · string · required

A unique name for this AI backend instance. Used in telemetry and logging.

ai.provider · object · required

The LLM provider configuration. Exactly one provider must be specified: openAI, gemini, anthropic, vertex, bedrock, or azureOpenAI.

AI-specific policies

When using an ai backend, the following additional policies are available:

Policy	Description
policies.ai.promptGuard	Inspect and filter LLM prompts and responses
policies.ai.prompts	Append or prepend system prompts
policies.ai.routes	Map URL paths to LLM operation types
policies.backendAuth	Provide API keys for the LLM provider

See the Prompt Guard guide for configuration details.

---

AWS backend

The aws backend type handles AWS-native integrations such as AWS Bedrock AgentCore.

backends:
- aws:
    agentCore:
      agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2:123456789:runtime/agent-id"
  policies:
    transformations:
      request:
        set:
          X-Amzn-Bedrock-AgentCore-Runtime-User-Id: "user-foo"

AWS backends use IAM/SigV4 authentication by default. Configure backendAuth.aws with explicit credentials, or rely on the instance’s IAM role for implicit authentication.