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/mcpThe 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/mcpAuthentication and tenant isolation
MCP uses Microsoft Entra bearer tokens for the AZExecute API. Both delegated users and service principals are supported.
• Assign the calling user, service principal, or agent identity an API role: User, Operator, or TenantAdmin.
• Delegated clients request https://api.azexecute.com/Standard.Access.
• Service principals request https://api.azexecute.com/.default after an API app role has been assigned.
• 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.
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.
| 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_read_api_operation |
Invoke a discovered read-only operation with server-side method enforcement. |
invoke_api_operation |
Invoke one discovered write 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. |
For the full REST API contract, including operations that are intentionally REST-only, use the live API Swagger.
Applications and API Permission Requests
AI agents can discover and use supported application import, lifecycle, and permission-request operations without constructing paths or guessing permission identifiers.
1. Use search_api_operations to find application listing, import, permission discovery, request creation, or review operations.
2. Use get_api_operation to inspect the exact route, role, grant type, and body schema.
3. For internal APIs, discover the target application's delegated scopes or application roles before creating the request.
4. For external APIs such as Microsoft Graph, discover the API and its available permissions before creating the request.
5. Obtain confirmation before invoking imports, permission requests, approvals, or other consequential operations.
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. Use invoke_read_api_operation for reads, invoke_api_operation for confirmed write operations, or a dedicated automation-task tool when 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.
• Only operations returned by MCP discovery can be invoked through the generic API tool.
• Credential, secret, private-key download, backup, billing, and integration-secret operations are intentionally unavailable through MCP; use the documented REST API when authorized access to those operations is required.
• 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.