> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getunblocked.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom MCP
> Connect an HTTP MCP server to Unblocked
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](/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:
```json theme={null}
{
"name": "search_logs",
"description": "Search application logs",
"annotations": {
"readOnlyHint": true
}
}
```
## Connect a custom MCP server
In the Unblocked sidebar, click **Settings**, then **Data Sources**, then **Connect another data source**. Select **Custom**, then select **Custom MCP**.
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.
* **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.
Click **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.
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.
Click **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](/team-settings/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`.
### 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.
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](/user-settings/connecting-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.