> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/use-groundcover/connectors/mcp.md).

# Remote MCP Servers

The Remote MCP Servers connector lets [Agent Mode](/use-groundcover/agent-mode.md) use tools from external [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers. Admins allowlist Remote MCP Servers at the organization level, and individual users connect with their own tokens to access the tools those servers expose.

{% hint style="info" %}
Remote MCP Servers must be allowlisted by a workspace admin before users can connect. See [Connectors](/use-groundcover/connectors.md) for the two-tier model.
{% endhint %}

## Admin Setup

### Allowlisting a Remote MCP Server

1. Go to **Integrations → Connectors** and open the **Org Connectors** tab
2. Select **Remote MCP Servers** and click **Allowlist a Remote MCP Server**
3. Fill in the server details:
   * **Connector Name**: A unique name to identify this server
   * **URL**: The MCP server endpoint (e.g., `https://mcp.example.com/mcp`)
   * **Headers**: Optional key-value pairs sent with every request to the server
4. Click **Save**

The server is now available for users to connect to.

{% hint style="info" %}
Users can view the server's name, URL, and headers from their manage page, but cannot modify any details set by the admin.
{% endhint %}

{% hint style="info" %}
You can allowlist multiple Remote MCP Servers. Each one is added independently with its own Connector Name, URL, and tool restrictions. Repeat the steps above for each server you want to make available.
{% endhint %}

### Managing Tool Restrictions

To view and manage tools, you first need to provide an admin token:

1. Click **Manage** on an allowlisted Remote MCP Server
2. In the **Tool Restrictions** section, enter your admin token
3. Once connected, the full list of available tools appears

{% hint style="info" %}
The admin token is stored securely and can be updated at any time from the Manage dialog.
{% endhint %}

Each tool can be set to one of three permission levels:

| Permission         | Behavior                                   |
| ------------------ | ------------------------------------------ |
| **Automatically**  | Tool executes without user approval        |
| **Needs Approval** | User must approve each execution (default) |
| **Deny**           | Tool is completely blocked                 |

**Default Behavior**: Sets the permission for all tools that don't have a custom override, and applies automatically to new tools the server adds in the future.

**Per-tool override**: Click the permission selector on an individual tool to override the default. A reset button appears on customized tools to revert them back to the default.

Use the search field to filter tools by name.

{% hint style="warning" %}
Admin tool restrictions act as the **ceiling** for user permissions. Users can make their own permissions more restrictive, but never more permissive than what the admin allows. See [How Tool Restrictions Work](#how-tool-restrictions-work) for details.
{% endhint %}

### Disabling Remote MCP Servers

Admins can disable the Remote MCP Servers connector at any time from **Integrations → Connectors** under the **Org Connectors** tab. When disabled, Agent Mode cannot use any MCP tools, even if users have already connected their tokens. User credentials and tool restriction settings are preserved, not deleted. Once the admin re-enables Remote MCP Servers, all previously configured user connections resume working as before.

### Removing a Remote MCP Server

Click **Remove** on the server in the credentials list. This disconnects all users from the server.

## User Setup

### Connecting to a Remote MCP Server

1. Go to **Integrations → Connectors → My Connections**
2. Select **Remote MCP Servers** and browse the list of servers your admin has allowlisted
3. Click **Connect** on the server you want to use
4. Enter your personal API token and click **Connect**

You'll be taken to the server's manage page where you can view its configuration and manage your tool restrictions.

{% hint style="info" %}
The server's name, URL, and headers are configured by your admin and displayed as read-only. Contact your admin if any details need to change.
{% endhint %}

### Listing Available Tools

The **Tool Restrictions** section at the bottom of the manage page shows every tool the server exposes, including each tool's name and description. Use the search field to filter the list.

### Managing Personal Tool Restrictions

You can set your own tool permissions using the same three levels as the admin, with one key difference, **your choices are capped by the admin's restrictions**.

| Permission         | Behavior                                   |
| ------------------ | ------------------------------------------ |
| **Automatically**  | Tool executes without user approval        |
| **Needs Approval** | User must approve each execution (default) |
| **Deny**           | Tool is completely blocked                 |

* **Default Behavior**: Sets your personal default for all tools without a custom override.
* **Per-tool override**: Customize individual tools. A reset button reverts a tool to your personal default.

Tools where the admin has set a more restrictive ceiling show a **lock icon** with a "Restricted by admin" tooltip. You cannot select a permission more permissive than what the admin allows.

### Updating Your Token

Click **Update Token** on the manage page to replace your personal API token.

### Disconnecting

Click the **Disconnect** button to remove your connection. You can reconnect at any time.

## How Tool Restrictions Work

Tool restrictions use a **least-permissive** model with two tiers:

1. **Admin tier**: The admin sets org-wide permissions (Automatically, Needs Approval, or Deny) per Remote MCP Server. These act as the maximum allowed permission.
2. **User tier**: Each user sets personal permissions that can only be **equal to or more restrictive** than the admin's setting.

The effective permission for any tool is always the most restrictive of the two tiers.

### Examples

| Admin Permission | User Permission | Effective Permission           |
| ---------------- | --------------- | ------------------------------ |
| Automatically    | Automatically   | Automatically                  |
| Automatically    | Needs Approval  | Needs Approval                 |
| Automatically    | Deny            | Deny                           |
| Needs Approval   | Automatically   | Needs Approval                 |
| Needs Approval   | Needs Approval  | Needs Approval                 |
| Needs Approval   | Deny            | Deny                           |
| Deny             | Any             | Deny, tool is blocked entirely |

This means:

* If the admin denies a tool, no user can use it.
* If the admin sets a tool to Needs Approval, users can keep it at Needs Approval or deny it, but cannot set it to Automatically.
* The admin's default permission also applies to **new tools** the server adds after initial setup.

## Troubleshooting

| Issue                           | Resolution                                                                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Remote MCP Server not listed    | Ask a workspace admin to allowlist the server under **Integrations → Connectors → Org Connectors → Remote MCP Servers** |
| "Restricted by admin" on a tool | The admin has set a more restrictive permission, contact your admin to change it                                        |
| Tools not loading               | Verify the admin has connected an admin token for the server; the server may also be unreachable                        |
| Connection failed               | Check that your personal token is valid and the MCP server is accessible                                                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/connectors/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.