Citadel publish contracts

Ref Detailed guide

Backend resources such as MCP servers and A2A-speaking agents need to be onboarded and published as AI assets, centrally protected by the gateway. Citadel uses Azure API Management (APIM) as the gateway.

A published asset is a governed entry point in the gateway. It contains:

  • APIM API type: mcp / a2a
  • Dedicated APIM backend for each remote MCP / A2A with circuit breaker and credential injection
  • Baseline policy with gateway's shared governance fragments (auth, usage metrics, alerting, etc.)
  • Optional: API Center registration

Asset-type path prefix: good idea to publish mcp servers under {gateway}/mcp and agents under {gateway}/agents.

Note: in APIM you can create MCP from an existing REST API. I find this a antipattern and I'm disregarding this option. This also simplifies policies, since we don't have to mess with suffixing /mcp Also, in this pattern you have to make an extra effort to keep the source API protected by injecting the subscription key of the source API, because APIM strips default subscription headers at the first hop (from client to MCP server).

How to record contracts?

  • IaC (Azure samples uses Bicep)
  • Each contract should be a self-contained reviewable unit
  • contracts/<contract-name>/<env>/main.bicepparam
  • Contracts are maintained and source-controlled by DevOps teams managing the backend resources.
    • In the accelerator code the contracts tree is git-ignored
    • TODO double check
  • Contracts are generated (with environment specific IDs) and validated

Question: investigate API Ops. Should also be declarative, but APIM native.

Asset fields

Which information should be recorded in a publish contract for an asset?

Some fields are shared, some depend on the type of asset.

I noticed that all asset types require a boolean "subscription required" and the string "subscription key header name", yet these are not recorded under "common".

TODO: investigate specifically how the subscription key header name is used at runtime. This seems like a great pattern because various tools require different auth headers.

Common

  • asset type: mcp | a2a
  • name
  • displayName
  • description
  • path
  • metadata
    • version
    • owner
    • contact email
    • compliance tags
    • classification (e.g. 'confidential', or use CIA )
  • ?policy XML
  • ?publish to API Center
  • ?apiCenter

Existing MCP

When exposing an existing MCP pattern (my preferred way), additionally record these fields:

  • transportType ('streamable' is currently the only sensible option here, we don't want to expose stdio servers)
  • subscription required (default: true)
  • subscription key header name (default: api-key)
  • backend
    • url
    • auth type
    • ?auth config
    • ?circtuitBreaker

A2A

  • agent ID
  • agent card path (default: /.well-known/agent.json)
  • agent card backend URL
  • json RPC path (default: /)
  • subscription required (default: false)
    • See note below
  • subscription key header name (default: api-key)
  • backend
    • url
    • auth type
    • ?auth config

NOTE: on whether a subscription is required. Currently (nov 2026) you cannot provide a subscription key to A2A because A2A is in preview and simply doesn't validate it and breaks if provided. If you don't require a subscription this will be an anonymous endpoint, which means the calling agent does not have to provide an API key. The gateway itself authenticates using the gateway managed identity, so communication with the backend Foundry keeps working. Client side auth is taken care of with the Citadel access contract.

Required RBAC: Foundry Agent Consumer or Azure AI User on the Foundry project.

MCP from API

Fields for the mcp-from-api pattern are not recorded here, see note above.

Backend auth & auth config

The auth config concerns auth with the backend asset (MCP, A2A), not auth towards APIM.

authType Use authConfig
none Public remote MCP —
managed-identity Foundry A2A, Azure-hosted backends { resource } (e.g. https://ai.azure.com)
api-key-header Remote server keyed by a header { headerName?, namedValueKey, keyVaultSecretUri? | secretValue? }
api-key-bearer Bearer-token server { namedValueKey, keyVaultSecretUri? | secretValue? } (store the full Bearer ... value)

Resiliency / circuit breaking

When using the remote MCP feature (which I prefer) each remote MCP requires a dedicated APIM backend to enable features like circuit breaking (and for LLMs, load balancing).

backend: {
  url: 'https://remote-mcp.contoso.com/mcp'
  authType: 'none'
  circuitBreaker: {          // optional per-asset override
    failureCount: 5
    failureInterval: 'PT1M'
    tripDuration: 'PT30S'
    acceptRetryAfter: true
  }
}

Usage tracking

Usage is emitted as App Insights custom metrics in the accelator code.

Metric Namespace deploymentName dim customDimension1 customDimension2
McpRequests mcp-usage tool / MCP name mcp operation
A2ARequests a2a-usage agent name a2a operation

Two scheduled Logic App workflows aggregate these metrics into Cosmos DB, cloned from the LLM usage workflow:

TODO: how does usage tracking translate to cost monitoring? This seems to be a great omissions currently in APIM x Foundry.

Things to explore:

  • Event hub
  • Datadog integration
  • PostgreSQL instead of Cosmos
  • Other ways to aggregate

Contraints and important considerations

As of november 2026:

A2A:

  • A2A is currently in preview (nov 2026) and does not support validation of subscription keys.
  • A2A assets do not create an APIM backend object because they auth using a full backend URL in the xml policy

MCP:

  • Policies should not read context.Response.Body, because this will buffer and break the streaming MCP SSE transport.
  • This implies that response side controls do not work for MCP
    • E.g. PII de-anonymization, response content-safety
    • Can be mitigated somewhat by vetting the MCP servers themselves
    • A2A v1.0 is non-streaming JSON-RPC, so response-side inspection should be safe there

Policies

MCP Fragments

  • TODO security-handler
  • mcp-usage
  • raise-alert-events

Baseline MCP

<!--
    Baseline policy for published Tools (MCP servers).

    Applied by default to every MCP asset created through the Citadel Publish Contract. It layers
    the gateway's shared governance fragments on top of the MCP endpoint:
      - security-handler : API key (+ optional per-product JWT) authentication / defense-in-depth
      - mcp-usage        : inbound request-count metric (mcp-usage namespace) for FinOps tracking

    IMPORTANT (MCP streaming constraint): do NOT read context.Response.Body in MCP policies. Doing so
    triggers response buffering, which breaks the streaming (SSE) behavior MCP servers require. All
    request inspection (auth, usage, and any opt-in PII/content-safety you add per asset) must happen
    INBOUND only. PII de-anonymization and response content-safety are therefore NOT supported for MCP.

    To layer additional controls (e.g. inbound PII anonymization or content safety) for a specific
    asset, supply a custom policyXml on that asset in the bicepparam instead of editing this baseline.
-->
<policies>
    <inbound>
        <base />
        <!-- Record which backend serves this tool so the usage metric can attribute calls -->
        <set-variable name="publishedBackendId" value="@(context.Api?.Name?.ToString() ?? "NA")" />
        <!-- Authentication (API key + optional JWT per access-contract product) -->
        <include-fragment fragment-id="security-handler" />
        <!-- Usage metric (inbound only; see streaming note above) -->
        <include-fragment fragment-id="mcp-usage" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
        <!-- Opt-in alerting on auth/backend/throttling failures (no-op unless enabled on the product) -->
        <include-fragment fragment-id="raise-alert-events" />
    </on-error>
</policies>

A2A Fragments

TODO

  • authentication-managed-identity
  • a2a-usage
  • raise-alert-events

Baseline A2A

<!--
    Baseline policy for published Agents (A2A endpoints).

    Applied by default to every A2A asset created through the Citadel Publish Contract.
      - authentication-managed-identity : the gateway authenticates to the (Foundry) agent backend with
        its managed identity (injected by publishA2aAgent.bicep in place of the {backendAuth} marker).
      - a2a-usage : inbound request-count metric (a2a-usage namespace) for FinOps tracking.

    Client-side auth: when the API is published with subscriptionRequired=true, APIM validates the caller's
    subscription (API) key natively — presented in the configured header (subscriptionKeyHeaderName: 'api-key'
    or 'Ocp-Apim-Subscription-Key'). When subscriptionRequired=false the endpoint is anonymous at the gateway.
    Richer client auth (JWT, product scoping) is layered on by the phase-2 Access Contract.

    A2A v1.0 is JSON-RPC and non-streaming (no SSE), so outbound response inspection is safe if needed
    (supply a custom policyXml). Foundry serves A2A v0.3 by default; send 'A2A-Version: 1.0' to select v1.0.
-->
<policies>
    <inbound>
        <base />
        <!-- Record the asset name so the usage metric can attribute calls -->
        <set-variable name="publishedBackendId" value="@(context.Api?.Name?.ToString() ?? "NA")" />
        <!-- Request uncompressed backend responses so the outbound agent-card rewrite works (find-and-replace
             cannot operate on a gzip-compressed body). -->
        <set-header name="Accept-Encoding" exists-action="override">
            <value>identity</value>
        </set-header>
        <!-- Backend (agent) authentication via managed identity -->
        <!-- {backendAuth} -->
        <!-- Usage metric -->
        <include-fragment fragment-id="a2a-usage" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <!-- Rewrite the agent card's backend (Foundry) transport URLs to the gateway so A2A/MAF clients
             route THROUGH the gateway instead of calling Foundry directly. Injected by publishA2aAgent.bicep. -->
        <!-- {cardRewrite} -->
    </outbound>
    <on-error>
        <base />
        <!-- Opt-in alerting on backend/throttling failures (no-op unless enabled) -->
        <include-fragment fragment-id="raise-alert-events" />
    </on-error>
</policies>