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 a Public API Collection, see Custom integrations.

​
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 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.

​
Enable Data Shield

Data Shield lets each team member use a Custom MCP data source with their own account and permissions. It is available for connections that use OAuth. Connections that use HTTP Headers do not support Data Shield. With Data Shield off, Unblocked uses the shared credentials configured when the data source was connected. Team members can receive information accessible to that shared account without connecting their own accounts. With Data Shield on, each member must connect their own account. Unblocked calls the MCP server with that member’s credentials, so the server applies their permissions. Only tools selected for the data source and available to that member can be used. If their account is disconnected or access is revoked, they must reconnect; Unblocked does not fall back to the shared account.
Custom MCP data sources protected by Data Shield can only be used in personal threads. Start a personal thread to use these tools.

​
Turn on Data Shield for a connection

An Unblocked admin can enable Data Shield after connecting the MCP server with OAuth.
  1. Go to Settings › Data Shield.
  2. Find the Custom MCP row for your connection. Use the Name column to distinguish between multiple MCP servers.
  3. Turn on its Status toggle, review the explanation, and click Enable Data Shield.
Each Custom MCP connection has its own setting. In the example below, Data Shield is enabled for miro.com. Data Shield settings with the miro.com Custom MCP connection enabled

​
How users connect their accounts

After an admin enables Data Shield, each member completes these steps, including the person who originally connected the data source:
  1. Go to Settings › User Accounts under Personal Settings.
  2. Under Unconnected Accounts, find the Custom MCP connection by name and click Connect My Account.
  3. Sign in to the service with your own account and authorize access.
User Accounts showing Connect My Account for the miro.com Custom MCP connection Repeat this for each protected Custom MCP connection you want to use. Until you connect your account, Unblocked cannot use that connection’s tools on your behalf. See User Accounts for more about managing connected accounts.

​
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.