Choose how to host and expose MCP servers on Azure¶
Draft outline: not validated
Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-30). Author: Sivaraj · dry-run: Sandeep Velu · sign-off: James. Work items: AGT-10-T05, AGT-10-T06, AGT-10-T07, AGT-10-T08.
1. Summary¶
When starting a new MCP server, when a client asks to reuse existing REST APIs as tools, or when deciding which protocol revision to support.
Risk: Medium (the wrong choice means re-platforming once several agents depend on the server). Typical duration: Half a day.
2. When to use and when not to¶
Use it when: When starting a new MCP server, when a client asks to reuse existing REST APIs as tools, or when deciding which protocol revision to support.
Do not use it when: to be written by the author.
3. What you must know first¶
- API Management can expose a managed REST API as an MCP server where each operation becomes a tool; only tools are supported, not resources or prompts
- API Management can also govern existing MCP servers with policies such as JWT validation and rate limits
- API Center can register remote and local MCP servers and offers a registry endpoint for discovery
- Streamable HTTP is the remote transport; HTTP+SSE is deprecated
- SDK v2 serves both 2026-07-28 and the earlier revision from one server; check client support before dropping older revisions
4. Options¶
Outline of the decision process; the author describes each option.
- If a well-documented REST API already exists, default to exposing it through API Management as an MCP server.
- If tools need custom logic, aggregation or multi-step calls, build a custom server on Container Apps.
- Put API Management in front of custom servers for auth, quotas and logging.
- Register every server in API Center so agents and developers can discover it.
- Choose supported protocol revisions from the clients you must serve and record them.
- Record the decision, owner and review date in the catalog entry.
Draft snippet: MCP hosting decision record
server: orion-invoice-tools
owner: agent-lead
decision:
pattern: custom-server-behind-apim # or apim-rest-as-mcp
hosting: azure-container-apps
gateway: azure-api-management
registry: azure-api-center
transport: streamable-http
protocol:
supported_revisions: ["2026-07-28", "2025-11-25"]
drop_older_after: client-upgrade-confirmed
reasons:
- tools aggregate two ERP calls, so plain REST exposure is not enough
- client requires Entra ID tokens validated at the gateway
review_date: 2027-03-31
Snippets to add:
snippets/docs/mcp-hosting-decision.yaml: Hosting decision record (yaml)snippets/docs/mcp-hosting-table.md: Decision table: APIM-exposed REST versus custom server (markdown)
5. Decision table¶
| Situation | Choose | Why |
|---|---|---|
| to be written |
6. Recommended default and when to deviate¶
To be written by the author from the outline above.
7. Known issues and fixes¶
| Symptom | Likely cause | Fix |
|---|---|---|
| API Management MCP server shows no tools | Operations not selected or API not imported correctly | Re-select operations as tools and check the API definition |
| Per-tool rate limits needed | API Management policies apply to all tools in a server | Split high-risk tools into a separate server or enforce limits in the backend |
| Old client cannot connect to a new server | Client only speaks an earlier protocol revision | Keep earlier revision support until clients upgrade |
8. Monitoring and alerts¶
| Signal | Alert when | Action |
|---|---|---|
| Calls by protocol revision | Clients still on a revision you plan to drop within 30 days | Contact client owners before removal |
9. AWS and open-source equivalents¶
On AWS, AgentCore Gateway converts APIs and Lambda functions into MCP tools, similar to API Management. Open-source teams host servers on Kubernetes and use the MCP registry for discovery.
10. Validation record¶
Pending. Planned dry-run scenario: A second engineer applies the guide to two sandbox systems, one with a REST API and one without. Pass: the decision records match the defaults or state a reason, and both servers appear in API Center.