Choose who the agent acts as

For example, an operations agent can run work allowed by its assigned role. With delegated access, “show my applications” uses the signed-in person's access, and a colleague using the same agent can see a different set of applications. Signing in does not grant extra AZExecute permissions. Both modes retain tenant boundaries, operation authorization, and applicable workflow approvals.

Follow Delegated access: create the connection, add the tool, and sign in. The alternative Connect as agent guide covers shared identities. This choice controls authorization to AZExecute; automation tasks still execute through their configured integration identities.

Connection details

Configure a client that supports remote MCP over Streamable HTTP with the following server URL:

The endpoint publishes OAuth protected-resource metadata so compatible clients can discover the Microsoft Entra authorization requirements:

Set up a delegated MCP tool in Microsoft Foundry

Recommended path for user assistants: follow steps 1–6 below to create the connection with AZExecute and enable secret rotation. If your OAuth client and connection are already configured, go to Add the tool. To configure OAuth directly in Foundry, use the manual setup reference.

Use OAuth identity passthrough when people should connect through their agent to AZExecute in their own context. AZExecute's guided setup configures the customer-owned OAuth client and Foundry connection, and its secret rotation integration keeps the connection's client secret current. The client secret authenticates the OAuth application; MCP calls still use the signed-in user's permissions.

How it works: a person asks the agent to do something → Foundry prompts that person to sign in → Entra issues a delegated token for the AZExecute API → the agent calls MCP with that token → AZExecute authorizes the operation as that user. Every colleague completes their own sign-in. The person who created the connection does not lend their permissions to other users.

For example, a User can ask the agent to run a task they are allowed to use, while an Operator can author workflows allowed by their access. Asking the agent to “act as an administrator” cannot change that access. Published-task rules, direct resource grants, ownership checks, and workflow approvals still apply. A permitted task runs with its configured execution identities, so delegated MCP access does not imply that every downstream script or integration uses the human's credentials.

1. Prepare the client application and access

Complete AZExecute tenant setup, then create or import a customer-owned Entra app registration into AZExecute, for example AZExecute-MCP-Delegate, in the same tenant as your Foundry project. This is the OAuth client whose secret AZExecute will manage. It is separate from the AZExecute API registration and the Foundry agent identity.

Each user needs their own AZExecute role and resource access. A recognized explicit Entra app role determines delegated API access; otherwise the user's configured AZExecute role applies. Granting the client Standard.Access allows delegated API access but does not give users additional roles. You do not need to assign the OAuth client an app-only Operator or TenantAdmin role for this flow.

Users also need at least Foundry Agent Consumer access on the project, in the project's tenant. Foundry access and AZExecute access are separate requirements. The person building the agent needs permission to configure its tools and project connections. These setup permissions are not required of every person using the finished agent.

The person running setup needs permission to manage that application in AZExecute and modify its Entra registration, delegated Microsoft Graph Application.ReadWrite.All consent for AZExecute, and access to discover the Foundry project and read, create/update, and read secrets from its connections. Activate eligible roles before starting. Background rotation needs separate permissions, described below.

2. Run the guided connection setup

1. Open the client application's Secrets → Microsoft Foundry settings and enable Rotate Foundry connection secret.
2. Select the Azure subscription, Microsoft Foundry account, and Foundry project, then choose Create connection.
3. Select the AZExecute preset and give the connection a name: 3–24 lowercase letters, numbers, or hyphens, starting with a letter or number.
4. Run the setup stages below. If a stage fails, correct the reported access or configuration issue and retry. An interrupted setup can resume with the same project, connection name, and OAuth settings.

Setup also supports Other MCP server for Entra-backed APIs: enter its HTTPS endpoint, resource API application (client) ID, and full delegated scopes separated by spaces. The resource API exposes the permissions; the application being managed remains the OAuth client. Use explicit scopes for one API, rather than .default; setup adds offline_access.

3. Save rotation and complete administrator setup

1. Choose Use connection, then save the application's Secrets settings with Secret Integration enabled and its lifetime and rotation schedule configured. Creating a connection does not save pending Secrets settings.
2. Grant AZExecute's configured Application identity connection read, write, and listsecrets access on the Foundry project, in addition to its application-secret management permissions. Setup checks this access but does not grant Azure roles. Use Recheck access after permissions are granted.
3. If tenant policy requires administrator consent for the OAuth client's requested API permissions, complete it through the client's API permissions link in the dialog.

4. Add the delegated connection as the agent's MCP tool

1. Open the same Foundry project and the agent that people will use. In Tools, choose Add and the Model Context Protocol (MCP) tool option.
2. Select the existing project connection created by AZExecute, using the connection name from step 2. Save it to the agent. If the portal presents a new-connection form, use its existing-connection selection rather than creating a second connection.
3. Check that the selected connection points to https://api.azexecute.com/mcp and uses OAuth identity passthrough / custom OAuth. Agent Identity and Project Managed Identity are the alternative shared-identity modes; selecting one changes whose permissions the tool uses.
4. Give the tool a recognizable name, such as azexecute-delegated, so users can identify it in the sign-in prompt and you can identify it in the tool trace. Keep host approval enabled for consequential operations.

The guided setup has already created the OAuth connection and registered its callback. Attaching it to the agent does not require another client secret. For a connection created directly in Foundry, use the manual OAuth settings below.

5. Each user signs in through the agent

1. In the playground or your agent application, ask “Show my applications in AZExecute”. On first use, follow the sign-in prompt for the delegated MCP tool.
2. Sign in with your own work account in the intended tenant and review the requested permissions. Depending on existing consent, Entra can show consent for both your organization's OAuth client and AZExecute. Administrator consent may already cover some prompts; it does not replace each user's authorization of the Foundry connection.
3. If Microsoft shows an additional connection confirmation page, verify that it is the connection you initiated before allowing access.
4. Close the completed sign-in window and continue the conversation. If the original request has not resumed, send it again. Look for an actual MCP tool result and application data, not only a “Sign in successful” message.

In your own agent application, handle Foundry's oauth_consent_request: display its consent_link to the current user, then continue with the original previous_response_id after authorization. Each user authorizes the tool connection in that project; route the sign-in flow to the person using the agent. See Microsoft's OAuth continuation examples.

6. Verify the user's context and credential renewal

1. Run the read-only connection test and inspect the actual tool trace. Confirm that the call used the delegated connection, especially if the agent also has a tool configured with an agent identity.
2. Compare returned applications or available tasks with the signed-in user's expected access. Test with a second user whose access differs, using that user's own agent session and sign-in. The first user's authorization must not give the second user additional access. Empty results can be correct for a user with no matching resources.
3. Test a manual secret rotation, then verify both a fresh sign-in and token refresh for an existing authorization. Successful initial sign-in does not by itself validate future rotation.

Scheduled and manual rotation publish the new application secret to the saved Foundry connection without depending on an interactive user session. The endpoint, OAuth settings, and other credentials are preserved. Unexpired application secrets remain available during rotation; a failed or unconfirmed update is recorded as incomplete for retry. Setup verification checks configuration and access, so it does not replace an end-to-end OAuth refresh test.

See Foundry secret rotation for existing connections and rotation requirements, and Microsoft's OAuth identity passthrough guide for the user authorization flow.

Manual delegated OAuth setup

Use this path if you create the connection directly in Foundry instead of using AZExecute's guided setup. Prepare a customer-owned Entra OAuth client registration in the project tenant, add the AZExecute API's delegated Standard.Access permission, complete any required administrator consent, and create a client secret. Keep the same user-access requirements from step 1 above.

In the agent's Tools → Add → Model Context Protocol (MCP) flow, create a connection using OAuth identity passthrough and Custom OAuth. Supply these values, replacing <tenant-id> with your Entra tenant ID:

Save the connection, copy its returned callback, and add it to the OAuth client's Authentication → Web redirect URIs in Entra before starting user sign-in. Preserve any existing redirect URIs. The callback belongs to this connection; do not substitute the MCP endpoint or copy another connection's callback. The client ID belongs to your OAuth client, not the AZExecute API or the Foundry agent identity.

Attach the connection to the agent, then follow each user's sign-in and verification steps. To automate credential renewal, select this existing connection under the client application's Secrets → Microsoft Foundry settings, verify the client ID, and save rotation. Without rotation configured, maintain the client's secret and the connection's stored value before expiry.

Other MCP clients

The same delegated model applies to other clients that support Entra user authentication for remote Streamable HTTP MCP. Configure https://api.azexecute.com/mcp and request https://api.azexecute.com/Standard.Access through the client's supported user sign-in flow. Register the callback and client type required by that host. Foundry's callback and confidential-client secret settings are specific to Foundry; follow your host's OAuth requirements. Each person must authenticate as themselves.

Verify the MCP connection

For normal use, ask for the outcome, for example: “Show my applications”. The agent should discover the relevant operation, inspect its contract, fetch the data, and answer in your language. It should not just list API routes or ask you to choose an API version. Use the diagnostic prompt below when you specifically want connection details.

In the agent playground, use a prompt such as:

Check the tool results in Foundry's trace. Tool discovery confirms the MCP connection; a read with statusCode: 200 and isSuccess: true also verifies the selected API operation. An empty result can be valid. Some reads still require specific resource access or a higher role. Follow the operation's pagination contract rather than assuming every API starts at page 0 or page 1.

Keep Foundry tool approval enabled for consequential tools, especially invoke_api_operation, run_automation_task, and cancel_automation_run. Tool descriptions and annotations guide the agent; the Foundry approval setting controls whether the host requires confirmation. AZExecute still checks authorization and any applicable workflow approvals on the server.

See Microsoft's MCP authentication guide for current Foundry connection options.

Alternative: connect as an agent identity in Foundry

Connect your Foundry agent using Microsoft Entra authentication. Foundry obtains and renews the API token for the selected identity. This connection does not require a copied access token or client secret.

1. Grant the calling identity API access

Use a Foundry project in your AZExecute tenant. Complete AZExecute tenant setup and consent, including any current agreements. Identify the service principal object ID of the identity that the connection will use.

In AZExecute, open System Access → API Access → Add Assignment. Select that service principal and assign the lowest API role required. Start with User for permitted self-service work. Use Operator or TenantAdmin only when the intended operations require those permissions. Match the object ID: the Foundry resource, project, and agent can have similarly named identities.

This is an app role assignment on the AZExecute API enterprise application in your tenant. Existing tenant consent alone does not grant a new identity access. Azure subscription and Foundry project roles do not grant AZExecute API access. The administrator creating the assignment needs the required Entra permissions; see Roles and Access.

2. Add the MCP tool

Open your agent in the Foundry portal. Under Tools, choose Add, then a custom Model Context Protocol (MCP) connection. Enter these settings and save the connection to the agent:

If you granted the project managed identity access in step 1, select Project Managed Identity instead of Agent Identity. Keep the endpoint and audience above. An “AI Gateway not enabled” notice does not prevent a direct connection.

Agent Identity and Project Managed Identity use the selected identity's permissions for everyone using that agent. For each person's own permissions, follow the delegated access setup instead.

Finish with the read-only connection test using this identity.

Authentication and tenant isolation

MCP uses Microsoft Entra bearer tokens for the AZExecute API. Both delegated users and service principals are supported.

See Roles and Access and Authenticate for role assignment and token examples.

What agents can use

The MCP endpoint keeps discovery compact and exposes the supported operations that are appropriate for AI-assisted use. An agent normally starts with discovery and uses dedicated automation-task tools for common task workflows.

Discovery provides a readable displayName. Stable operation IDs such as azexecute:GET:... are internal references between tools; agents are instructed to use business names in conversation unless you request technical API details. A search result or operation contract is documentation, not the requested tenant data.

Use get_workflow_guidance to understand the product workflow, even in clients without MCP resource support. It covers applications, requests, permissions, automation tasks, machines/scripts/runbooks, schedules, VM shutdown, certificates, event listeners, categories, and tenant administration. Operation results include workflowTopic and workflowContext. Discovery ranks short capability phrases by relevance, including common English and Danish terms; it does not search tenant records. If nothing matches, broaden the query or consult the guide before assuming a capability is unavailable.

API version selection is automatic: omit pathParameters.version. The gateway uses the newest supported, non-deprecated stable version advertised for that exact operation. The contract exposes defaultApiVersion and marks the MCP version parameter optional with its default. An explicit version remains possible for compatibility. Preview-only or deprecated-only operations have no automatic stable default; the gateway will not guess one. Normal REST route parameters remain unchanged.

Server instructions and tool guidance help the model, but do not guarantee identical behavior across models or override your host's approval policy. After an MCP deployment, reconnect or refresh tools and start a fresh conversation if the host is using an older contract. Verify both the returned data and the tool trace.

For the full REST API contract, including operations that are intentionally REST-only, use the live API Swagger.

Applications and API Permission Requests

Create a new application: use an Application Request, not import. Search for create application and inspect POST Application/Requests. Supply the required business information from the contract and any tenant validation feedback. An existing client ID or object ID is not required. Do not invent owners, permissions, or business justification. Submit once, keep the returned request ID, and read the request to track approval and provisioning. A request ID or Requested/Queued state does not mean the Entra application has been created.

Discover requirements before creating an application

Your agent can read your organization's application request rules before asking questions. Call GET /api/v1/Application/Requests/Requirements with the same identity used to submit the request. This public REST endpoint is also available through MCP and does not require access to TenantAdmin settings. Application licensing and authentication still apply.

The result includes creationEnabled, approvalRequired, apiPermissionRequestsEnabled, and minimumAdditionalOwners. Each field describes its name, label, type, enabled/required state, limits, defaults and any configured options. A requiredWhen condition makes elevated-permission justification required when elevated access is selected. The default criticality of 3 and an answer of false for elevated permissions are valid values. Disabled metadata fields do not need answers; existing values are preserved according to the update contract. Department and environment option values are display names, not abbreviations or IDs, and remain suggestions compatible with existing free-text values.

1. Read requirements for each new request in the active tenant. Static API schemas alone cannot express your organization's current settings. If creation is disabled, stop and explain the policy.
2. Use the user's existing answers, ask for missing required information and any applicable conditional fields, and offer the configured choices. Do not invent a business justification or fill required fields with placeholders.
3. Resolve requested co-owners through the lookup below. The minimum is the number of distinct additional owners, excluding the requester. For API access, use permission options and their IDs; grant types are AppRole, DelegatedScope and, where supported, AuthorizedClient.
4. Send the proposed creation body to POST /api/v1/Application/Requests/Validate. In MCP, inspect this operation and call invoke_read_api_operation with the draft as body. This reviewed validation operation is read-only despite using POST.
5. Check isValid, not just HTTP 200. Correct each returned field, code and message, then validate again. Once valid and authorized, submit through POST /api/v1/Application/Requests and follow the returned request ID.

Validation saves nothing and performs no directory or provisioning actions. It checks input and current tenant policy, including required metadata, field lengths, owner counts and permission-request shape. It does not prove owner existence, name uniqueness, external permissions, consent or provisioning success. Submission checks current policy again and can still fail; an unresolved requested owner causes failure rather than silently creating without that owner. Validation errors on submission return HTTP 400 with field errors. This preflight is for creation; read the existing request before preparing an update or review.

For example, an agent asked to create Customer Portal with a named co-owner first reads the requirements and resolves the person. If your tenant requires a department and business justification, it asks for those missing answers. It validates your answers and submits with the verified owner. You do not need to know the API's field names or object IDs.

Owners by name or email: you can ask the agent to create an application with a named co-owner. The agent should read the application-requests and tenant-users workflow guides, discover find owner, and inspect the returned operation. It then calls GET Application/CoOwnerCandidates with the person's name, email or sign-in name in search. Searching the operation catalog for a person's email does not search the directory.

The lookup returns the candidate's id, name, mail and userPrincipalName; the compatibility email field prefers the sign-in name. The agent compares the actual results and uses the selected id in the request's coOwnerUserIds. This is the Entra user object ID in the active tenant, not an application client ID or a guest's home-tenant user ID. You should not need to look up a UUID yourself. If several people match, the agent asks you to choose; if none match, it explains that result. Results are capped at 100, so broad searches may need narrowing. A directory permission or consent failure must be reported as a lookup failure, not as a missing person.

For example: Create an application called Customer Portal with alex@example.com as co-owner. The expected workflow is to look up Alex, inspect the request contract, collect any missing business information, submit with the verified co-owner ID, and read the saved request to confirm its owners and status. The authenticated requester is recorded separately. The agent must not drop a requested co-owner to get past a lookup problem unless you explicitly change the requirement. On an update, it reads the current request and preserves existing owners and permissions that you did not ask to change.

Directory candidates and tenant users are different: Application/CoOwnerCandidates searches Entra users for application ownership and can find people who do not yet have an AZExecute tenant-user record. Delegated calls use the signed-in user's Graph access when available; app-only calls use the tenant's configured Application integration. Existing tenant, licensing and directory authorization checks still apply. Finding someone does not grant them access or assign ownership.

For administration of existing AZExecute users, discover tenant users and inspect GET TenantAdmin/Users in the tenant-admin document. This requires TenantAdmin access and supports search, zero-based page, pageSize, and totalItems in the response. Deleted users and service principals are hidden unless explicitly included. Inspect the returned identity flags, effectiveRole, roleSource and isRoleSourceVerified before drawing conclusions about access. This inventory is not the full Entra directory, and an agent does not need TenantAdmin inventory access merely to discover the application co-owner lookup.

Track the request: use GET Application/Requests/{requestId} with the returned integer request ID. Read coOwners, state and stateReason; approval and provisioning are separate stages. Only report the application as created after the returned state and resulting application confirm it. Keep the same request while waiting, and check it after a lost response before submitting again. API permission drafts use the request permission-options endpoints and requestedApiPermissions; selecting an owner does not grant API permissions. See Application Requests for business information and tenant policy requirements.

Import an existing application: use the import information and candidates endpoints to select an existing Entra registration. Import and application creation are different workflows. Approval requirements depend on tenant policy; the agent must not change that policy to finish a request.

ShowAllApplications gives visibility, not deletion rights. An Operator must still be an AZExecute owner and have owner deletion enabled, or the caller must be TenantAdmin. A service principal acts under its own identity, not the permissions of the human chatting with it. For a visible application, insufficient deletion rights produce 403; a hidden or missing application may produce 404.

The applicationId route parameter accepts the application's internal id GUID, Entra applicationObjectId, or applicationId (Client ID). A service principal ID is not an alias. The agent should take identifiers from actual tool results, verify the application with a read, and confirm the effect before deletion. A 404 is not proof that an application was deleted; a 409 ambiguous_application_identifier requires resolving the ambiguity before any write. See Application identifiers and deletion semantics.

AI agents can discover and use supported application import, lifecycle, and permission-request operations without constructing paths or guessing permission identifiers. For APIs beyond the common PermissionRequests/ExternalApis catalog, use PermissionRequests/TenantApplications with a name prefix or exact client/object ID, then pass the returned appId into External permission options. Existing owners' application-specific notifications can be changed through the owner notification operation. These are shared public REST API operations that other clients can use too.

Recommended agent workflow

Security boundaries

Troubleshooting

For ACME account setup, DNS validation, issuance and parameterized deployment scripts, follow Certificate automation with MCP. The agent has separate workflow guides for accounts, DNS, deployment tasks and scripting.

OAuth consent popup errors: the OAuth client's Web redirect URI must exactly match the redirectUrl returned by that Foundry connection. Guided setup registers and verifies this value automatically. A callback from another connection is not interchangeable. Start sign-in through Foundry's authorization prompt; opening the callback directly is not a sign-in test. If tool calls succeed after a popup error, capture the error text, time, correlation ID, and popup hostname/path for investigation. Omit the URL query string and fragment, which can contain authorization codes or state.

Failed generic API calls are marked with MCP isError=true and retain structured statusCode, isSuccess, and safe response details. HTTP success at the transport level is not business success. An accepted asynchronous operation is not completion: read its request, run, job, or operation status with bounded, spaced polling. After a timeout or lost response to a write, inspect existing state before retrying to avoid duplicate requests or runs. For support, include the operation, time, status, and any traceId or request reference. Never include bearer tokens or credentials.

Build workflows with enabled integrations

MCP supports automation authoring as well as task execution. Operators and TenantAdmins can list, inspect and run published or unpublished tasks in their tenant and discover enabled integrations without receiving credentials. Users can run published tasks permitted by their publication role, or tasks with effective direct resource access of User level or higher, even when unpublished. Viewer access alone does not allow execution. A direct task Editor grant also permits the relevant authoring lookups, but does not bypass required approvals, licensing or integration permissions.

1. Read get_workflow_guidance with topic automation-authoring. Search for the authoring API operations, inspect their contracts, and invoke the reads.
2. Read Tasks/Authoring/StepTypes, then the selected step type. Each contract includes supported task types, the exact configType, configuration schema, an example stepTemplate, enum choices, integration binding and expected outputs. Templates still need real targets and validation.
3. Read Tasks/Authoring/Integrations to select an enabled connection. Follow pagination; optionally filter by integrationType. Inspect its supported steps, mode and allowed operations. Enabled does not guarantee remote connectivity or permissions.
4. Resolve targets through the supported task lookups: machines, applications, key vaults, gateways, directory objects, DNS connections/zones, TOPdesk, SCOM, Micetro, DevOps, GitHub and Azure resources/storage. Do not invent IDs. Azure DNS connection IDs are references, not credentials.
5. Create a task through Tasks/Management; its definition is saved immediately. Add configured steps, parameter links, conditions and execution layout as required. Use the returned IDs and preserve existing fields when editing. Keep dependent steps sequential.
6. Validate the saved task and correct its reported issues. Read back its configuration before intended use. Validation records diagnostics; it does not execute the task, change its publication flag, or prove that external operations will succeed.
7. Publish only if self-service availability is requested. Publication is optional. The dedicated MCP task-run tools follow existing execution access, including authorized unpublished tasks: retrieve the task's input contract, execute only when authorized, respect approvals and track its status. The returned published flag and minimumRole describe self-service publication, not a requirement to publish before running. Enabling schedules or event listeners can cause future execution.

Reusable inputs and live resource selectors

Ask the agent to read get_workflow_guidance(topic=automation-parameters) when designing inputs. Custom parameters are more than text boxes: use typed values or fixed dropdowns for simple choices, GraphResources for Azure Resource Graph results, and integration-backed selectors for Active Directory, Entra users/groups or Micetro IPAM. For example, let someone choose a VM by name while passing its resource ID, or choose an AD user/group while passing the distinguished name required by a step. GraphResources is not Microsoft Graph.

Reuse an appropriate parameter, configure its lookup connection and value/display fields, link it to the task, and bind its technical name into the step. A parameter's lookup connection does not configure the step's execution connection. Directories support single or multiple selection where the receiving step accepts it. Shared definition changes affect every linked task; use per-task overrides for local defaults and required status. See Custom Parameters for details.

Graph lookups normally require delegated user credentials; system lookup uses the configured Automation application and its Azure permissions. An app-only agent must not assume a delegated identity or switch identity to bypass a denial. An empty options list with valueSource=DynamicLookup does not mean there are no choices. Follow the input's lookup.operationId, passing the task ID and exact input name, or call its REST lookup.path. The task-scoped lookup returns bounded value/displayName choices and accepts search; it requires task run access, not authoring access. Pass the selected value under that input name, using an array only when multiple values are allowed. Preview the selected values and validate bindings before requesting a run.

Example agent request

When inspecting existing workflows, execution integration IDs are inside each step's config, for example config.activeDirectoryIntegrationId. Parameter lookups can use a different integration. A disabled step may still have a configured connection, and safe task-run tools intentionally omit implementation details. Read the management task detail before concluding that a connection is missing; do not overwrite a valid task based on an absent legacy field.

Tasks have no draft state. Report saved configuration, validation, publication and execution separately. A missing required step value may need a literal value or a supported variable binding; it does not automatically require a new interactive input. The legacy draftStepTemplate field is only an alias for stepTemplate, not a task status. All server guidance is in English; agents can answer in your language. Refresh the MCP connection after deployment to load updated contracts. Server instructions improve discovery but cannot guarantee a model's behavior; retain host-side confirmations and verify the saved configuration and actual run results.