--- title: "MCP servers API | Grafana Cloud documentation" description: "Register and manage Model Context Protocol server integrations for Grafana Assistant with the HTTP API." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # MCP servers API Use MCP server integrations to connect external [Model Context Protocol](https://modelcontextprotocol.io/) servers to Assistant. MCP servers provide tools that Assistant can use during conversations, such as querying external APIs, searching documentation, or performing actions in third-party systems. MCP server integrations have two scopes: - **Tenant integrations** are available to all users in the organization. Use tenant integrations when you manage MCP servers through the HTTP API, because they apply for all users across the organization. - **User integrations** are available only to the identity that created them. You can’t create user integrations on behalf of other users. The API path for MCP servers is `/integrations`. Examples use the base URL and service account token described in [Grafana Assistant HTTP API reference](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis). ## Create an MCP server Register a new MCP server integration. **Endpoint** `POST /integrations` **Permissions** Expand table | Integration scope | Required permission | |-------------------|--------------------------------------------| | `user` | `grafana-assistant-app.mcps.user:create` | | `tenant` | `grafana-assistant-app.mcps.tenant:create` | **Request** Send a JSON request body. Expand table | Field | Required | Description | |-----------------|----------|------------------------------------------------------------------------------------------------------------------------------------| | `name` | Yes | Display name for the integration. | | `scope` | Yes | Integration scope: `user` or `tenant`. | | `type` | Yes | Integration type. Use `mcp`. | | `enabled` | Yes | Whether the integration is active. | | `applications` | Yes | Applications the integration applies to. Valid values: `assistant`, `loop`, `all`. Defaults to `["all"]` when empty. | | `configuration` | No | MCP server configuration. | | `customHeaders` | No | Custom HTTP headers sent to the MCP server. Each entry requires `key` and `value`. Values are encrypted and redacted in responses. | | `description` | No | A short description of the integration. | **Configuration** The `configuration` field contains MCP server settings. Expand table | Field | Description | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `url` | The MCP server URL. | | `toolPreferences` | A map of tool names to `enabled` or `disabled`. Controls whether each tool is available to Assistant. Tools not listed default to `enabled`. | | `toolApprovalPolicies` | A map of tool names to `auto_approve` or `always_ask`. Controls whether Assistant can run the tool without user confirmation. Tools not listed use the default policy, which auto-approves read-only tools and asks for others. | Tool names are defined by the MCP server. You can discover available tool names by connecting the server through the Grafana UI or by calling the server’s MCP `tools/list` method directly. JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "Internal docs server", "scope": "tenant", "type": "mcp", "enabled": true, "applications": ["assistant"], "configuration": { "url": "https://docs-mcp.internal.example.com/mcp/", "toolPreferences": { "delete_records": "disabled" }, "toolApprovalPolicies": { "update_record": "always_ask", "search_docs": "auto_approve" } }, "customHeaders": [ {"key": "Authorization", "value": "Bearer your-token-here"} ] } ``` **Response** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "d6e4f5a7-8901-2345-bdef-167890123456", "created": "2025-11-15T11:00:00Z", "modified": "2025-11-15T11:00:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "updatedBy": "sa-5594@serviceaccount.grafana", "name": "Internal docs server", "type": "mcp", "enabled": true, "scope": "tenant", "applications": ["assistant"], "configuration": { "url": "https://docs-mcp.internal.example.com/mcp/", "toolPreferences": { "delete_records": "disabled" }, "toolApprovalPolicies": { "update_record": "always_ask", "search_docs": "auto_approve" } }, "customHeaders": [ {"key": "Authorization", "value": "**********"} ] } } ``` Header values are redacted in responses. **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X POST "${ASSISTANT_API_URL}/integrations" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \ -d '{ "name": "Internal docs server", "scope": "tenant", "type": "mcp", "enabled": true, "applications": ["assistant"], "configuration": { "url": "https://docs-mcp.internal.example.com/mcp/" }, "customHeaders": [ {"key": "Authorization", "value": "Bearer your-token-here"} ] }' ``` ## List MCP servers Retrieve integrations with optional filtering and pagination. **Endpoint** `GET /integrations` **Permissions** Expand table | Integration scope | Required permission | |-------------------|------------------------------------------| | `user` | `grafana-assistant-app.mcps.user:read` | | `tenant` | `grafana-assistant-app.mcps.tenant:read` | **Request** Expand table | Parameter | Required | Description | |----------------|----------|------------------------------------------------------------------------| | `scope` | No | Filter by scope: `user` or `tenant`. | | `enabled_only` | No | When `true`, return only enabled integrations. | | `limit` | No | Maximum number of integrations to return. Range: 1-100. Default: `20`. | | `offset` | No | Pagination offset. Default: `0`. | **Response** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "integrations": [ { "id": "d6e4f5a7-8901-2345-bdef-167890123456", "created": "2025-11-15T11:00:00Z", "modified": "2025-11-15T11:00:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "updatedBy": "sa-5594@serviceaccount.grafana", "name": "Internal docs server", "type": "mcp", "enabled": true, "scope": "tenant", "applications": ["assistant"], "configuration": { "url": "https://docs-mcp.internal.example.com/mcp/" }, "customHeaders": [ {"key": "Authorization", "value": "**********"} ] } ], "pagination": { "total": 1, "limit": 20, "offset": 0 } } } ``` **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X GET "${ASSISTANT_API_URL}/integrations?scope=tenant&enabled_only=true" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" ``` ## Get an MCP server Retrieve a single integration by ID. **Endpoint** `GET /integrations/{id}` **Permissions** Expand table | Integration scope | Required permission | |-------------------|------------------------------------------| | `user` | `grafana-assistant-app.mcps.user:read` | | `tenant` | `grafana-assistant-app.mcps.tenant:read` | **Request** Expand table | Parameter | Required | Description | |-----------|----------|-------------------------------------------------------------| | `id` | Yes | The integration ID returned when you create an integration. | **Response** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "d6e4f5a7-8901-2345-bdef-167890123456", "created": "2025-11-15T11:00:00Z", "modified": "2025-11-15T11:00:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "updatedBy": "sa-5594@serviceaccount.grafana", "name": "Internal docs server", "type": "mcp", "enabled": true, "scope": "tenant", "applications": ["assistant"], "configuration": { "url": "https://docs-mcp.internal.example.com/mcp/" }, "customHeaders": [ {"key": "Authorization", "value": "**********"} ] } } ``` **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash INTEGRATION_ID="d6e4f5a7-8901-2345-bdef-167890123456" curl -X GET "${ASSISTANT_API_URL}/integrations/${INTEGRATION_ID}" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" ``` ## Update an MCP server Update an existing integration. Only the fields you include in the request body are changed, except `scope` which is always required. **Endpoint** `PUT /integrations/{id}` **Permissions** Expand table | Integration scope | Required permission | |-------------------|-------------------------------------------| | `user` | `grafana-assistant-app.mcps.user:write` | | `tenant` | `grafana-assistant-app.mcps.tenant:write` | **Request** Expand table | Parameter | Required | Description | |-----------|----------|---------------------| | `id` | Yes | The integration ID. | Send a JSON request body with the fields to update. Expand table | Field | Required | Description | |-----------------|----------|-----------------------------------------------------------| | `scope` | Yes | The current scope of the integration: `user` or `tenant`. | | `name` | No | Updated display name. | | `description` | No | Updated description. | | `enabled` | No | Whether the integration is active. | | `applications` | No | Updated application list. | | `configuration` | No | Updated MCP server configuration. See **Configuration**. | | `customHeaders` | No | Updated custom HTTP headers. | **Response** The response contains the full updated integration. JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "d6e4f5a7-8901-2345-bdef-167890123456", "created": "2025-11-15T11:00:00Z", "modified": "2025-11-20T14:15:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "updatedBy": "sa-5594@serviceaccount.grafana", "name": "Internal docs server", "type": "mcp", "enabled": false, "scope": "tenant", "applications": ["assistant"], "configuration": { "url": "https://docs-mcp.internal.example.com/mcp/" }, "customHeaders": [ {"key": "Authorization", "value": "**********"} ] } } ``` **Examples** Disable an integration: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash INTEGRATION_ID="d6e4f5a7-8901-2345-bdef-167890123456" curl -X PUT "${ASSISTANT_API_URL}/integrations/${INTEGRATION_ID}" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \ -d '{ "scope": "tenant", "enabled": false }' ``` ## Delete an MCP server Permanently delete an integration. **Endpoint** `DELETE /integrations/{id}` **Permissions** Expand table | Integration scope | Required permission | |-------------------|--------------------------------------------| | `user` | `grafana-assistant-app.mcps.user:delete` | | `tenant` | `grafana-assistant-app.mcps.tenant:delete` | **Request** Expand table | Parameter | Required | Description | |-----------|----------|---------------------| | `id` | Yes | The integration ID. | **Response** A successful deletion returns HTTP 204 with no response body. **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash INTEGRATION_ID="d6e4f5a7-8901-2345-bdef-167890123456" curl -X DELETE "${ASSISTANT_API_URL}/integrations/${INTEGRATION_ID}" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" ```