Skip to main content
Connect any Model Context Protocol (MCP) server that is available over public HTTPS to let Unblocked use its tools when answering questions. This includes hosted MCP servers from services such as Grafana or Miro, as well as MCP servers created or operated by your team. Use this option when you need live context from a system that doesn’t have a built-in Unblocked data source. Unblocked only makes read-only MCP tools available. You choose which of those tools Unblocked can use. If you are deciding between Custom MCP and pushing documents through the Unblocked API, see Choose a custom data source.

​
Before you connect

Make sure you have:
  • The publicly reachable HTTPS endpoint for the MCP server you want to connect. Local, private-network, and HTTP endpoints aren’t supported.
  • An MCP server that supports tool discovery and provides clear, accurate descriptions for its tools. This can be a hosted third-party server or one operated by your team.
If your server uses HTTP headers for authentication, you also need the header names and values it expects, such as an API key or bearer token. You can also provide a public image URL if you want to override the generated data source icon.
Unblocked uses annotations.readOnlyHint when the MCP server provides it. If the hint is missing, Unblocked evaluates the tool’s description and excludes tools that might modify data. Only tools determined to be safely read-only are available for selection.
To explicitly identify a tool as read-only, include the hint in its definition:

​
Connect a custom MCP server

1

Open Custom MCP settings

In the Unblocked sidebar, click Settings, then Data Sources, then Connect another data source. Select Custom, then select Custom MCP.Select Custom MCP from the Custom data source category
2

Enter the server details

Complete the connection form:
  • MCP server URL: The public HTTPS endpoint for the MCP server, including its MCP path when required. For example, https://mcp.example.com/mcp.
  • Name: Unblocked generates a name from the server URL. You can replace it with a more recognizable name.
  • Icon URL: Unblocked generates an icon from the server URL. You can replace it with another public image URL.
Choose how Unblocked authenticates with the MCP server:
  • OAuth: Select this option if your MCP server supports OAuth. When you click Connect, you’re redirected to the MCP server to authorize access. Connect to a Custom MCP server with OAuth
  • HTTP Headers: Select this option to send custom headers with every MCP request. Enter both a name and value for each header, and click Add Header if the server requires more than one.
For bearer-token authentication, use Authorization as the header and Bearer YOUR_TOKEN as its value. Use the header names required by your MCP server for other authentication methods.Connect to a Custom MCP server with HTTP headersClick Connect. After you authorize with OAuth, or immediately when using HTTP headers, Unblocked validates the endpoint, connects to the server, and discovers its tools. Discovery can take up to a minute.
3

Select tools

Select the read-only tools that Unblocked can use. Use the filter to find a tool by its name or description, or use the MCP Tools checkbox to select or clear all tools.Tools that can modify data don’t appear in this list.Select the read-only tools Unblocked can use from the connected MCP serverClick Save Settings. Unblocked can now use the selected tools when they are relevant to a question.

​
Authentication and access

With OAuth, Unblocked redirects you to the MCP server to authorize access. With HTTP headers, Unblocked encrypts the values you provide and sends them with every request to the MCP server. Use a dedicated, least-privilege credential that grants access only to the data the selected tools need. The tool names and descriptions returned by your MCP server help Unblocked decide when to use each tool. Use clear descriptions that explain what each tool returns and when it is useful.

​
Manage the connection

To change the available tools, go to Settings › Data Sources, open the custom MCP data source, update the selection, and click Save Settings. Use the settings menu on the data source to manage or disconnect it.

​
Troubleshooting

​
The Connect button is unavailable

Check that:
  • MCP server URL and Name aren’t empty.
  • Every HTTP header row has both a name and a value, or is completely empty.
  • Header names are unique. Header-name matching isn’t case-sensitive.

​
Unblocked can’t connect to the server

Confirm that the URL:
  • Starts with https://.
  • Points to the MCP endpoint, not only the server’s website or API root.
  • Resolves to a host that is reachable from the public internet.
  • Supports the selected authentication method and responds within one minute.

​
The custom icon isn’t displayed

Unblocked generates an icon from the server URL. To override it, make sure the custom icon URL is publicly accessible and points directly to an image. If the image can’t be loaded, Unblocked displays its default MCP icon instead.