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. 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.
Create an MCP server
Register a new MCP server integration.
Endpoint
POST /integrations
Permissions
Request
Send a JSON request body.
Configuration
The configuration field contains MCP server settings.
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.
{
"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.
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
Request
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
Request
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}"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
Request
Send a JSON request body with the fields to update.
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
Request
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}"
