Foundry MCP Tool Governance Demo (APIM + Entra OAuth Passthrough)

Use Case

This repository demonstrates user-level governance for custom MCP tools used by Azure AI Foundry agents.

Goal:

1. Keep agents and tools in Foundry.
2. Use OAuth identity passthrough in the Foundry MCP tool configuration.
3. Enforce user/group access in APIM using Entra-issued claims (roles/groups).

Result:

1. Foundry agent invokes MCP tool through APIM.
2. APIM validates Entra token and required role/group claims.
3. Only authorized users can invoke the MCP tool.

End-to-End Architecture

1. User signs in and invokes agent.
2. Foundry MCP tool uses OAuth passthrough to obtain delegated user token.
3. APIM MCP endpoint validates token audience and claims.
4. APIM forwards valid calls to backend API/tool implementation.

Prerequisites

1. A working API in APIM (already tested independently).
2. An MCP server created in APIM from that working API.
3. A Foundry project with a deployed model.
4. Python 3.10+ and Azure CLI (az login) for local script execution.

1. Microsoft Entra Configuration

1.1 Create API App Registration (resource API)

1. Create app registration, for example mcp-api-app.
2. In Expose an API, set Application ID URI, for example api://<API_APP_CLIENT_ID>.
3. Add delegated scope mcp.invoke.
4. Add app role:
   • Display name: McpInvoke
   • Value: McpInvoke
   • Allowed member types: Users/Groups
   • Description: Allows invoking MCP tools through APIM.

1.2 Create Client App Registration (OAuth client)

1. Create app registration, for example foundry-mcp-client.
2. In Authentication, add platform Web.
3. Add Foundry-generated redirect URI (from MCP tool OAuth setup flow).
4. In API permissions, add delegated permission to api://<API_APP_CLIENT_ID>/mcp.invoke.
5. Grant admin consent if your tenant requires it.

1.3 Enterprise Application Assignments

1. Go to Enterprise applications -> <API app enterprise app> -> Users and groups.
2. Assign users or groups to role McpInvoke.
3. Optional: set Assignment required = Yes on client enterprise app to control who can use client sign-in.

Expected claims in access token at APIM:

1. aud = api://<API_APP_CLIENT_ID>
2. roles contains McpInvoke (role-based governance)
3. scp may include mcp.invoke (delegated scope)

2. APIM Configuration

2.1 Create MCP Server from Existing API

1. Start from an already working API in APIM.
2. Create MCP server from that API and select tool operations to expose.

2.2 MCP Policy to Enforce Role Assignment

Apply this policy on the MCP endpoint (.../mcp) and keep validation above <base />.

<policies>
  <inbound>
    <validate-azure-ad-token tenant-id="<TENANT_ID>">
      <audiences>
        <audience>api://<API_APP_CLIENT_ID></audience>
      </audiences>
      <required-claims>
        <claim name="roles">
          <value>McpInvoke</value>
        </claim>
      </required-claims>
    </validate-azure-ad-token>
    <base />
  </inbound>
  <backend><base /></backend>
  <outbound><base /></outbound>
  <on-error><base /></on-error>
</policies>

Important:

1. Keep MCP endpoint policy minimal. Avoid request/response rewrites on MCP route.
2. Keep backend routing/transforms on the underlying API operations, not on MCP route.
3. If testing auth behavior, disable subscription enforcement everywhere unless intentionally used.

3. Foundry Tool and Agent Setup

3.1 Create Custom MCP Tool in Foundry

1. In Foundry project, add custom MCP tool.
2. Set server URL to APIM MCP endpoint, for example https://<apim-name>.azure-api.net/<mcp-server-name>/mcp.
3. Configure OAuth identity passthrough.
4. Provide OAuth client/API settings (from Entra apps):
   • Client ID: <CLIENT_APP_CLIENT_ID>
   • Client Secret: <CLIENT_APP_CLIENT_SECRET_VALUE>
   • Scope: api://<API_APP_CLIENT_ID>/mcp.invoke
   • Authorize URL: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize
   • Token URL: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
   • Refresh URL: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
5. Complete consent flow and confirm tool connectivity.

3.2 Create Agent in Foundry

1. Create a Foundry agent in the same project.
2. Attach the MCP tool created above.
3. Save and use this agent reference for runtime invocation.

4. Using create_and_run.py for OAuth Passthrough Agents

File: scenario2_foundry_hosted_agent/create_and_run.py

4.1 Prepare Environment

1. Copy .env.example to .env.
2. Set:
   • FOUNDRY_PROJECT_ENDPOINT
   • FOUNDRY_MODEL_DEPLOYMENT_NAME
   • FOUNDRY_EXISTING_AGENT_REFERENCE=<agent-name>:<version>
   • FOUNDRY_MCP_SERVER_LABEL
   • FORCED_TOOL_QUERY
   • OPEN_OAUTH_CONSENT_IN_BROWSER=true|false

4.2 Install Dependencies

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

4.3 Run

python scenario2_foundry_hosted_agent/create_and_run.py

4.4 Runtime Behavior

1. Uses DefaultAzureCredential (your az login user) for agent invocation.
2. Invokes existing agent reference.
3. Detects oauth_consent_request; prints consent URL and can open browser when enabled.
4. Auto-approves mcp_approval_request and continues run.
5. Writes full payload to scenario2_foundry_hosted_agent/runtime_response_debug.json.

Optional: Script-Based Agent Creation

The script currently defaults to invoking an existing agent.

There is a commented scaffold in main() for service-principal-based agent creation with MCP tool attachment:

1. Set SP values in .env (FOUNDRY_SP_TENANT_ID, FOUNDRY_SP_CLIENT_ID, FOUNDRY_SP_CLIENT_SECRET).
2. Uncomment the SP creation block in main().
3. If using script creation, agent creation in Foundry portal can be skipped.

Files

1. scenario2_foundry_hosted_agent/create_and_run.py
2. .env.example
3. requirements.txt