Merge pull request #312848 from hhunter-ms/hh-559950

[AMG] Add docs for AMG-MCP

Author: JamesJBarnett

articles/managed-grafana/grafana-mcp-server.md

@@ -0,0 +1,169 @@
+---
+title: Configure an Azure Managed Grafana remote MCP server
+description: Discover MCP tools for Azure Managed Grafana. Query Application Insights, Azure Data Explorer, and more with secure authentication and easy setup.
+#customer intent: As a developer, I want to configure my application to interact with the AMG-MCP endpoint so that I can programmatically manage my Azure Managed Grafana instance.
+author: weng5e
+ms.author: wuweng
+ms.reviewer: malev
+ms.date: 03/09/2026
+ms.topic: concept-article
+ms.service: azure-managed-grafana
+---
+
+# Configure an Azure Managed Grafana remote MCP server
+
+Every Azure Managed Grafana instance includes a built-in Model Context Protocol (MCP) server endpoint called AMG-MCP. The AMG-MCP endpoint allows tools and applications to interact programmatically with the Grafana instance using the MCP. The AMG-MCP endpoint uses the same authentication mechanism as the Grafana instance, supporting both Entra ID and the Grafana service account token.
+
+## Endpoint path
+
+The AMG-MCP endpoint path format is `https://<grafana-endpoint>/api/azure-mcp`. For example, the endpoint could look like: `https://my-grafana-<guid>.<location>.grafana.azure.com/api/azure-mcp`.
+
+## Available MCP tools
+
+AMG-MCP provides the following tools for interacting with Azure Managed Grafana:
+
+| Tool Name | Description |
+|-----------|-------------|
+| `amgmcp_insights_get_failures` | Get Failures insights. Returns failure summary data from Application Insights, such as failed requests, failed dependencies, and exceptions. |
+| `amgmcp_insights_get_agents` | Get GenAI agent insights. Returns GenAI agent related information from Application Insights, such as agent invocations, token usage, and latency. Queries data following 'OpenTelemetry for Generative AI' Semantic Conventions. |
+| `amgmcp_kusto_get_metadata` | Get the metadata for connected Azure Data Explorer (Kusto) clusters. Lists all Azure Data Explorer data sources, and for each data source, gets the clusterUrl, databases and schema. |
+| `amgmcp_kusto_query` | Query data in Azure Data Explorer (Kusto) cluster. |
+| `amgmcp_mssql_get_metadata` | Get the metadata for all connected Microsoft SQL Server data sources. Lists the databases, tables, and column schemas for each Microsoft SQL Server data source. |
+| `amgmcp_mssql_query` | Query data in a Microsoft SQL Server data source. |
+| `amgmcp_query_application_insights_trace` | Query Application Insights Trace through Grafana Azure Monitor data source. When trace data is stored in multiple Application Insights, this tool aggregates the data. |
+| `amgmcp_query_azure_subscriptions` | List all the Azure subscriptions that the Grafana Azure Monitor data source can access. |
+| `amgmcp_query_resource_graph` | Query Azure Resource Graph (ARG) through Grafana Azure Monitor data source. |
+| `amgmcp_query_resource_log` | Query Azure Resource Log through Grafana Azure Monitor data source. |
+| `amgmcp_query_resource_metric` | Query Azure Resource Metric values through Grafana Azure Monitor data source. |
+| `amgmcp_query_resource_metric_definition` | Query Azure Resource Metric Definitions through Grafana Azure Monitor data source. |
+| `amgmcp_dashboard_search` | Search for Grafana dashboards by a query string. Returns a list of matching dashboards with details like title, UID, folder, tags, and URL. |
+| `amgmcp_datasource_list` | List all Grafana data sources. |
+
+## MCP configuration
+
+To connect to the AMG-MCP endpoint, you need to configure your MCP client with the appropriate settings. AMG-MCP supports two authentication methods:
+
+- [**Grafana service account token:**](#grafana-service-account-token) A token generated from your Grafana instance (format: `glsa_xxx`)
+- [**Entra ID token:**](#entra-id-token) An Azure AD/Entra ID token (e.g., from a managed identity or service principal)
+
+### Grafana service account token
+
+Use a Grafana service account token for authentication. Start by creating a token:
+
+1. In the Grafana instance UI, navigate to **Administration > Service accounts**.
+1. [Create a new service account using the appropriate permissions.](./how-to-service-accounts.md#create-a-service-account)
+1. [Generate a token](./how-to-service-accounts.md#add-a-service-account-token)
+1. Copy the Grafana service account token (format: `glsa_xxx`) and paste into your configuration settings:
+
+    ```json
+    {
+      "my-grafana-mcp-server": {
+        "disabled": false,
+        "timeout": 60,
+        "type": "streamableHttp",
+        "url": "https://my-grafana-d5ggtqegcr2safcp.wcus.grafana.azure.com/api/azure-mcp",
+        "headers": {
+          "Authorization": "Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxx"
+        }
+      }
+    }
+    ```
+
+### Entra ID token
+
+Use an Entra ID token (Azure AD token) for authentication. This approach is useful when using managed identities or service principals.
+
+1. Use the Azure CLI to obtain an Entra ID token associated with the Azure Managed Grafana resource ID:
+
+    ```bash
+    az account get-access-token --resource ce34e7e5-485f-4d76-964f-b3d2b16d1e4f --query accessToken -o tsv
+    ```
+
+1. Alternatively, use a managed identity to acquire a token programmatically with the Azure Managed Grafana audience `ce34e7e5-485f-4d76-964f-b3d2b16d1e4f`.
+
+    ```json
+    {
+      "my-grafana-mcp-server": {
+        "disabled": false,
+        "timeout": 60,
+        "type": "streamableHttp",
+        "url": "https://my-grafana-d5ggtqegcr2safcp.wcus.grafana.azure.com/api/azure-mcp",
+        "headers": {
+          "Authorization": "Bearer <entra-id-token>"
+        }
+      }
+    }
+    ```
+
+## Examples
+
+The following examples further demonstrate configuring AMG-MCP in your settings.
+
+### Example 1: Visual Studio Code configuration
+
+To configure MCP for Visual Studio Code, use configuration settings similar to the following example.
+
+```json
+{
+  "<your-grafana-mcp-server-name>": {
+    "type": "http",
+    "url": "https://<grafana-endpoint>/api/azure-mcp",
+    "headers": {
+      "Authorization": "Bearer <token>"
+    }
+  }
+}
+```
+
+**Configuration parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `type` | Transport type. Use `http` for remote MCP endpoints. |
+| `url` | The AMG-MCP endpoint URL: `https://<grafana-endpoint>/api/azure-mcp` |
+| `headers.Authorization` | Bearer token - either a Grafana service account token or an Entra ID token. |
+
+### Example 2: Cline configuration
+
+To configure MCP for Cline, use configuration settings similar to the following example.
+
+```json
+{
+  "<your-grafana-mcp-server-name>": {
+    "disabled": false,
+    "timeout": 60,
+    "type": "streamableHttp",
+    "url": "https://<grafana-endpoint>/api/azure-mcp",
+    "headers": {
+      "Authorization": "Bearer <token>"
+    }
+  }
+}
+```
+
+**Configuration parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `disabled` | Set to `false` to enable the MCP server connection. |
+| `timeout` | Connection timeout in seconds. |
+| `type` | Transport type. Use `streamableHttp` for remote MCP endpoints. |
+| `url` | The AMG-MCP endpoint URL: `https://<grafana-endpoint>/api/azure-mcp` |
+| `headers.Authorization` | Bearer token - either a Grafana service account token or an Entra ID token. |
+
+
+## Limitation
+
+Currently, AMG-MCP endpoint is included with Azure Managed Grafana instances only in Azure Public Cloud, not in sovereign clouds. 
+
+## Troubleshooting
+
+If you encounter any issues, open an issue in the [Azure Managed Grafana GitHub repo](https://aka.ms/managed-grafana/issues). 
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Configure MCP for AI Foundry agents](./how-to-configure-mcp-for-ai-foundry.md)
+>
+> [!div class="nextstepaction"]
+> [Enable zone redundancy](./how-to-enable-zone-redundancy.md)

articles/managed-grafana/how-to-configure-mcp-for-ai-foundry.md

@@ -0,0 +1,131 @@
+---
+title: Configure Azure Managed Grafana MCP for Azure AI Foundry agents
+description: Learn how to configure Azure Managed Grafana MCP in Azure AI Foundry so your agent can query Azure resources, metrics, and logs.
+author: weng5e
+ms.author: wuweng
+ms.reviewer: malev
+ms.date: 03/09/2026
+ms.topic: how-to
+ms.service: azure-managed-grafana
+#customer intent: As an AI engineer, I want to connect my Azure AI Foundry agent to the Azure Managed Grafana MCP endpoint so that the agent can query Azure resources and observability data.
+---
+
+# Configure Azure Managed Grafana MCP for Azure AI Foundry agents
+
+This article shows how to configure the Azure Managed Grafana MCP endpoint in an Azure AI Foundry agent. After configuration, your agent can use MCP tools to query Azure resources, metrics, logs, and dashboards through your Azure Managed Grafana workspace.
+
+## Prerequisites
+
+- An Azure subscription with permission to create and manage Azure resources.
+- An Azure Managed Grafana workspace. If you need one, see [Quickstart: Create an Azure Managed Grafana workspace](./quickstart-managed-grafana-portal.md).
+- An Azure AI Foundry project where you can create an agent.
+- Permission to assign Azure role-based access control (RBAC) roles on the Azure Managed Grafana resource.
+- A configured Grafana data source for the workloads you want the agent to query (for example, Azure Monitor for Resource Graph, metrics, and logs). For setup guidance, see [Configure data sources](./how-to-data-source-plugins-managed-identity.md).
+
+## Get your Azure Managed Grafana endpoint
+
+You use the endpoint hostname when you configure the tool in Foundry.
+
+1. In the [Azure portal](https://portal.azure.com), open your Azure Managed Grafana resource.
+1. On the **Overview** page, copy the **Endpoint** value. For example: `my-grafana-<id>.<region>.grafana.azure.com`.
+
+    :::image type="content" source="media/how-to-configure-mcp-for-ai-foundry/1-find-grafana-endpoint.png" alt-text="Screenshot of Azure portal showing the Azure Managed Grafana endpoint on the Overview page." lightbox="media/how-to-configure-mcp-for-ai-foundry/1-find-grafana-endpoint-expanded.png":::
+
+## Grant your Foundry project identity access to Azure Managed Grafana
+
+Your Azure AI Foundry project uses a managed identity to access tools and data sources.
+
+1. In the Azure portal, open your Azure Managed Grafana resource.
+1. Select **Access control (IAM)** > **Add** > **Add role assignment**.
+1. Assign one of these roles to the Foundry project managed identity:
+
+   - **Grafana Admin**
+   - **Grafana Editor**
+   - **Grafana Viewer**
+
+   Choose the least privileged role that satisfies your scenario.
+
+To find the correct principal:
+
+1. Open your Foundry project in Azure portal. 
+1. Use the managed identity shown under **Identity**.
+
+> [!NOTE]
+> Role assignments can take a few minutes to propagate. If the first validation attempt fails with authorization errors, wait and try again.
+
+:::image type="content" source="media/how-to-configure-mcp-for-ai-foundry/2-add-role-based-access-control.png" alt-text="Screenshot of Azure portal showing a role assignment being added to Azure Managed Grafana." lightbox="media/how-to-configure-mcp-for-ai-foundry/2-add-role-based-access-control-expanded.png":::
+
+## Create an agent in Azure AI Foundry
+
+1. Open [Azure AI Foundry](https://ai.azure.com) and go to your project.
+1. Select **Agents** > **+ New agent**.
+1. Select a model that supports tool calling. In this example, we use `gpt-5.1`.
+1. Enter a name and description for the agent.
+
+    :::image type="content" source="media/how-to-configure-mcp-for-ai-foundry/3-create-new-agent.png" alt-text="Screenshot of Azure AI Foundry showing the New agent creation flow." lightbox="media/how-to-configure-mcp-for-ai-foundry/3-create-new-agent-expanded.png":::
+
+## Add the Azure Managed Grafana MCP tool
+
+1. In the agent configuration, go to **Tools**.
+1. Select **+ Add tool**.
+1. Select **Catalog**, then select **Azure Managed Grafana**.
+
+    :::image type="content" source="media/how-to-configure-mcp-for-ai-foundry/4-agent-add-mcp.png" alt-text="Screenshot of Azure AI Foundry agent tool catalog with Azure Managed Grafana selected." lightbox="media/how-to-configure-mcp-for-ai-foundry/4-agent-add-mcp-expanded.png":::
+
+1. Configure the tool settings:
+
+   | Setting | Value |
+   | --- | --- |
+   | **workspace-hostname** | Your Azure Managed Grafana endpoint hostname. Enter only the hostname. Don't include `https://` or `/api/azure-mcp`. |
+   | **Authentication** | **Microsoft Entra** |
+   | **Type** | **Project Managed Identity** |
+   | **Audience** | The application ID for Azure Managed Grafana: `ce34e7e5-485f-4d76-964f-b3d2b16d1e4f` |
+
+
+    :::image type="content" source="media/how-to-configure-mcp-for-ai-foundry/5-mcp-config.png" alt-text="Screenshot of Azure AI Foundry showing Azure Managed Grafana MCP tool configuration values." lightbox="media/how-to-configure-mcp-for-ai-foundry/5-mcp-config-expanded.png":::
+
+## Validate the sample
+
+After you save the tool configuration, validate the setup from the agent chat.
+
+1. Open the chat panel for your agent.
+1. Submit a connectivity prompt, like *List all Azure subscriptions available through Azure Managed Grafana MCP*.
+1. Confirm that the response includes grounded tool output rather than a generic model-only answer.
+
+    :::image type="content" source="media/how-to-configure-mcp-for-ai-foundry/6-agent-trigger-resource-graph.png" alt-text="Screenshot of Azure AI Foundry chat where the agent invokes Azure Managed Grafana MCP tools." lightbox="media/how-to-configure-mcp-for-ai-foundry/6-agent-trigger-resource-graph-expanded.png":::
+
+### Sample prompts
+
+You can use any of the following sample prompts:
+
+- `List all Azure Managed Grafana instances in my subscriptions.`
+- `Show me all virtual machines in resource group <resource-group-name>.`
+- `Find all storage accounts with public access enabled.`
+
+### Troubleshoot validation
+
+If validation fails:
+
+- Verify the managed identity has a Grafana role on the Azure Managed Grafana resource.
+- Verify the **workspace-hostname** value is the Grafana hostname only.
+- Verify the audience is `ce34e7e5-485f-4d76-964f-b3d2b16d1e4f`.
+- Verify the Grafana data source required by the prompt exists and can access the target Azure scope.
+- Check for RBAC propagation delay and retry after a few minutes.
+
+## Clean up resources
+
+If you created resources only for this test, remove access and resources to avoid ongoing charges.
+
+1. Remove the test role assignment from your Azure Managed Grafana resource:
+
+   1. Open **Access control (IAM)** on the Azure Managed Grafana resource.
+   1. Select **Role assignments**.
+   1. Find the Foundry project managed identity assignment and remove it.
+
+1. In Azure AI Foundry, remove the Azure Managed Grafana tool from the agent, or delete the test agent.
+1. Optionally delete test resources such as the Foundry project and Azure Managed Grafana workspace if they were created only for this walkthrough.
+
+## Next steps
+
+- Learn more about the remote MCP endpoint in [Configure an Azure Managed Grafana remote MCP server](./grafana-mcp-server.md).
+- Explore dashboard examples in [Create dashboards for GenAI applications](./azure-ai-foundry-dashboard.md).