AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/toolbox/references/tool-mcp-managed-oauth.md

Tool — Remote MCP server, OAuth (Foundry-managed connector) (type: mcp)

Attach a remote MCP server whose OAuth is brokered by Foundry — you do not supply client_id / client_secret. Use when the MCP server appears as a catalog tile ("Custom · Preview" / a connector-namespace connector) and you accept Microsoft's managed OAuth app. Foundry owns the app registration, token storage, and refresh; the first tools/list triggers a one-time per-user consent.

For the variant where you own the OAuth app (BYO client_id / client_secret), see tool-mcp-custom-oauth.md. For the connector-namespace gateway_connector variant, see foundry-tool-catalog.md → Gateway connector full flow.

🚦 Before creating a toolbox/connection, read create-hosted.md → Toolbox creation boundary.

There is no redirect-URI round-trip and no client_secret to manage — the two things the managed flow removes versus tool-mcp-custom-oauth.md.


Getting the catalog inputs

Only the MCP tiles this query returns support managed OAuth. Run the discovery script with --managed-oauth — it lists exactly the tiles you can attach with this reference:

../scripts/get-catalog-inputs.sh --managed-oauth      # bash
pwsh ../scripts/get-catalog-inputs.ps1 -ManagedOAuth  # PowerShell

Find the user's tile in the output and take the connectorName, toolEntityId, and serverUrl it prints for the CLI below. If the tile is not in this list, managed OAuth does not apply to it — it uses a different auth mode.


A. Imperative CLI

Steps 1–3 of toolbox.md § The flow. Managed OAuth maps to azd ai connection create --auth-type oauth2 with --connector-name and --metadata, but NO --client-id / --client-secret — omitting the client credentials selects the Foundry-managed app (sends empty credentials: {}).

# 0. Install the CLI extension (once)
azd extension install azure.ai.toolboxes

# 1. Create the managed-OAuth (catalog_MCP) connection — no client id/secret
azd ai connection create github-mcp-managed \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp \
  --auth-type oauth2 \
  --connector-name foundrygithubmcp \
  --metadata type=catalog_MCP \
  --metadata toolEntityId=azureml://location/eastus/apiCenter/registry-prod-bl/type/tools/objectId/github-mcp-server/version/1 \
  --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

# Write the toolbox spec to a file (create takes a --from-file PATH; stdin '-' not supported)
cat > github-mcp.yaml <<'EOF'
description: github-mcp toolbox (managed OAuth)
connections:
  - name: github-mcp-managed
EOF

Create a new toolbox (first version auto-promoted):

azd ai toolbox create github-tools --from-file github-mcp.yaml --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

toolbox create / delete require an azd environment (run inside an azd init'd dir). connection create and toolbox create print a benign no active azd environment line even on success — check for the ... created line, not the warning.

Add to an existing toolbox (new version — then promote):

azd ai toolbox connection add github-tools github-mcp-managed --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"
azd ai toolbox publish github-tools <new-version> --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

connection add creates a new immutable version; the default stays unchanged until you publish.

The GitHub Copilot MCP server (api.githubcopilot.com/mcp) accepts the managed connector's tokens but rejects BYO OAuth-App tokens — the reverse of the BYO doc's caveat, and a reason to prefer managed for that server. See foundry-tool-catalog.md caveat.


B. Declarative azure.yaml

Create the managed-OAuth connection first (section A, step 1), then reference it by name via project_connection_id and azd deploy agent-tools — the same host: azure.ai.toolbox shape as every MCP variant. See tool-mcp-noauth.md § B for the full azure.yaml skeleton.

    tools:
      - type: mcp
        server_label: github_mcp
        project_connection_id: github-mcp-managed   # the connection name from section A
        require_approval: never

The -32006 consent gate below still applies — the first tools/list triggers the same one-time consent.


Verify

Call tools/list against the endpoint — see test-endpoint.md. The first call for an un-consented user returns the -32006 consent gate (managed differs only in that Foundry's app already allow-lists its own redirect — no callback registration). See test-endpoint.md § OAuth consent flow.

MCP-sourced tools surface as {server_label}___{tool_name} (three underscores). See mcp-protocol.md § Tool naming.

Managed-connector troubleshooting

| Symptom | Likely cause / fix | |---|---| | tools/list returns zero after consent | Wrong --target (not the MCP server URL), or the connector needs the gateway_connector two-PUT flow instead — see foundry-tool-catalog.md. | | invalid_payload: unsupported authType | API version drift — re-check allowed authType for RemoteTool in the projects REST API. | | 403 Forbidden on connection PUT | Caller lacks Foundry Project Manager (or Cognitive Services Contributor) on the project — grant at project scope. | | 403 Forbidden on toolbox data-plane POST | Caller lacks Foundry User on the project — grant at project scope. |

References