Platform

Assistant

SDK

HTTP API

MCP servers

Grafana Cloud

MCP servers API

Use MCP server integrations to connect external Model Context Protocol 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. The server configuration is shared, but each user can authorize a separate OAuth connection when the server requires it. 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.

You can also manage MCP servers with Terraform. Refer to the Grafana provider’s grafana_assistant_mcp_server resource.

Examples use the base URL and service account token described in Grafana Assistant HTTP API reference.

Create an MCP server

Endpoint

POST /integrations

Permissions

Integration scope	Required permission
`user`	`grafana-assistant-app.mcps.user:create`
`tenant`	`grafana-assistant-app.mcps.tenant:create`

Request

Send a JSON request body.

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.
`oauthRegistrationType`	No	OAuth client registration: `dynamic` or `preregistered`. Omit to use automatic discovery when the server requests OAuth.
`oauthClientId`	No	Client ID when `oauthRegistrationType` is `preregistered`.
`oauthClientSecret`	No	Optional client secret for a pre-registered client. Write-only; public clients can omit it.
`oauthScopes`	No	Space-separated OAuth scopes. Omit to use the server defaults.

Configuration

The configuration field contains MCP server settings.

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.

OAuth client settings belong to the server configuration. OAuth authorization belongs to the current user: creating a tenant integration doesn’t connect every user. Each user connects their account in Assistant settings. Custom headers remain part of the shared server configuration; a user’s OAuth bearer token replaces only a configured Authorization header for that user’s connection.

{
  "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

{
  "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. OAuth client secrets and user OAuth tokens aren’t returned.

Examples

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

Integration scope	Required permission
`user`	`grafana-assistant-app.mcps.user:read`
`tenant`	`grafana-assistant-app.mcps.tenant:read`

Request

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

{
  "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

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

Integration scope	Required permission
`user`	`grafana-assistant-app.mcps.user:read`
`tenant`	`grafana-assistant-app.mcps.tenant:read`

Request

Parameter	Required	Description
`id`	Yes	The integration ID returned when you create an integration.

Response

{
  "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

INTEGRATION_ID="d6e4f5a7-8901-2345-bdef-167890123456"

curl -X GET "${ASSISTANT_API_URL}/integrations/${INTEGRATION_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"

The integration response describes the server configuration, not whether a particular user has connected. To check the caller’s access and discover tools, call GET /integrations/{id}/validate. The response’s data.result.status is success, oauth_required, or failed; data.result.connected reports whether the caller has a non-revoked OAuth connection. A missing connection doesn’t affect other users of a tenant integration.

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

Integration scope	Required permission
`user`	`grafana-assistant-app.mcps.user:write`
`tenant`	`grafana-assistant-app.mcps.tenant:write`

Request

Parameter	Required	Description
`id`	Yes	The integration ID.

Send a JSON request body with the fields to update.

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.
`oauthRegistrationType`	No	Updated OAuth client registration type. Set to an empty string to clear the OAuth configuration.
`oauthClientId`	No	Updated pre-registered client ID.
`oauthClientSecret`	No	Updated client secret. Omit to retain the stored secret when the client ID is unchanged.
`oauthScopes`	No	Updated space-separated OAuth scopes.

Changing the server URL, registration type, client ID, or scopes can require connected users to authorize again. Rotating only the client secret preserves existing connections.

Response

The response contains the full updated integration.

{
  "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:

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

Integration scope	Required permission
`user`	`grafana-assistant-app.mcps.user:delete`
`tenant`	`grafana-assistant-app.mcps.tenant:delete`

Request

Parameter	Required	Description
`id`	Yes	The integration ID.

Response

A successful deletion returns HTTP 204 with no response body.

Examples

INTEGRATION_ID="d6e4f5a7-8901-2345-bdef-167890123456"

curl -X DELETE "${ASSISTANT_API_URL}/integrations/${INTEGRATION_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"