Citadel publish contracts
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>