Add a custom MCP server

Connect any compatible Model Context Protocol server to Assistant to extend capabilities beyond built-in integrations. Custom servers work with internal tools, third-party services, or specialized MCP implementations that provide functionality for your organization’s workflows.

What you’ll achieve

Use this guide to connect custom MCP servers to Assistant for specialized workflows and internal tools.

Configure custom MCP servers by providing endpoint URLs and authentication.
Filter discovered tools to optimize performance for your use case.
Control tool execution through manual confirmation during conversations.

Before you begin

Ensure you have the necessary requirements before configuring a custom MCP server.

Endpoint URL: Obtain the base URL for your MCP server that’s accessible from your Grafana instance.
MCP compatibility: Verify the server implements the Model Context Protocol specification. Assistant requires the server to use the streamable-http transport.
Authentication: Ensure the server supports OAuth, prepare a service token for a custom auth header (required for tenant-level scope), or verify public access for endpoints without authentication.
Expected tools: Review the server’s tool documentation and plan to filter to the minimum required tools.
Permissions: Refer to Manage Assistant access with RBAC - Understand available roles for the roles and permissions required to add personal or tenant MCP servers.
Network access: Ensure the MCP server allows inbound connections.

Configure the server

Add a custom MCP server by providing endpoint details and authentication.

To configure a custom MCP server:

Open the Assistant Settings and click Integrations.
Under MCP Servers, click Add Custom Server.
Enter a Name to identify the server in your integration list.
Choose a Scope:
- Personal (user): Visible only to you; uses OAuth for authentication.
- Tenant (everybody): Visible to your organization; requires a custom auth header.
Enter the Server URL for your MCP server endpoint, for example, https://mcp.example.com/api.
Optionally configure Authentication:
- OAuth: If your server supports OAuth, the OAuth flow will be initiated automatically upon saving.
- Custom auth header: Provide the value to be sent in the Authorization header (for example, Bearer YOUR_TOKEN, YOUR_API_KEY). This is required for tenant-level servers.
- No auth: Choose for public endpoints that don’t require authentication.
Click Save to validate connectivity and discover tools.

Manage MCP server

After configuration, you should filter tools and manage the server lifecycle. For information on filtering tools to improve performance and confirming tool calls during conversations, refer to Improve accuracy with tool filtering and Confirm tool calls manually. To learn how to enable, disable, or remove servers, refer to Manage server lifecycle.