MCP | AZExecute

Use MCP with AI agents

AZExecute provides a remote Model Context Protocol (MCP) endpoint that lets authorized AI agents discover and use the same supported automation capabilities as the customer API.

Agents can inspect available operations, understand their parameters and role requirements, run approved work, and monitor results without receiving access to internal implementation details.

Connection details

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

MCP server

https://api.azexecute.com/mcp

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

https://api.azexecute.com/.well-known/oauth-protected-resource/mcp

Your MCP client must support Microsoft Entra authentication or allow an access token for the AZExecute API to be supplied. A general Microsoft Graph token cannot be used.

Authentication and tenant isolation

MCP uses the same Microsoft Entra bearer token, API audience, and authorization rules as a direct REST API call. Both delegated users and service principals are supported.

• Assign the calling user, service principal, or agent identity an API role: User, Operator, or TenantAdmin.

• Request a token for the AZExecute API audience.

• The tenant and principal are taken exclusively from the validated access token.

• The agent cannot select another tenant or elevate its assigned role through an MCP argument.

• A separate MCP deployment is not required for each customer tenant.

Treat an agent identity like any other workload identity. Grant only the lowest API role and resource access required for its intended work.

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

What agents can use

The MCP endpoint keeps discovery compact while providing complete coverage of the supported customer API. An agent normally starts with the discovery tools and uses dedicated automation-task tools for common task workflows.

Capability	Purpose
`search_api_operations`	Search supported customer API operations by text, method, API area, or tag.
`get_api_operation`	Read the exact operation contract, including parameters, request schema, content types, roles, and consequence information.
`invoke_api_operation`	Invoke one discovered operation using the authenticated caller's existing API permissions.
`list_automation_tasks`	List published automation tasks available to the caller.
`get_automation_task`	Read a published task and its safe parameter contract.
`run_automation_task`	Start an authorized task with validated parameter values.
`list_automation_task_runs`	List recent run summaries for a published task.
`get_automation_run`	Read the current state of an automation run.
`cancel_automation_run`	Request cancellation of a non-terminal run.
`MCP resources`	Read capability guidance, automation-task contracts, and the supported customer API descriptions.

Each documented operation reports its accepted API roles. The server still performs the authoritative authorization check when the operation is called.

Recommended agent workflow

1. Connect the agent to https://api.azexecute.com/mcp.

2. Authenticate using a delegated user or service principal with an assigned API role.

3. Use search_api_operations to find the relevant capability.

4. Use get_api_operation to inspect parameters, accepted content types, allowed roles, and whether the operation changes state.

5. Confirm the intended target and material effect before invoking a consequential operation.

6. Call invoke_api_operation, or use a dedicated automation-task tool when one is available.

7. Read the returned status and poll the corresponding run resource when work is asynchronous.

Security boundaries

• MCP applies the same tenant, role, licensing, approval, resource-access, validation, and audit rules as the REST API.

• Agents cannot submit an arbitrary server URL or undocumented API path.

• Internal UI, connected-agent, callback, worker, and live-console routes are not included in MCP discovery.

• Sensitive implementation steps, stored secrets, raw exception details, and internal runtime values are not returned by the dedicated task tools.

Troubleshooting

• 401 Authentication required: acquire a fresh token for the correct API audience and reconnect the MCP client.

• 403 Access denied: verify the identity has an assigned API role and the necessary resource access.

• Operation not found: search again instead of constructing an operation identifier or path manually.

• Client cannot connect: confirm it supports remote Streamable HTTP MCP and Microsoft Entra bearer authentication.