> 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 choose token or OAuth authentication. Individual users then connect their own account to access the tools those servers expose. For services that already appear as their own connector card, follow that service's setup guide in [Connectors](/use-groundcover/connectors.md). Use **Remote MCP Servers** for any other compatible server. {% 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`) * **Authentication Method**: Select **Token** or **OAuth** * **Client ID** and **Client Secret**: Optional fields shown for OAuth; see [OAuth Client Registration](#oauth-client-registration) * **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. ### OAuth Client Registration When **Authentication Method** is **OAuth**, choose the setup that matches the MCP server: * **Dynamic client registration**: Leave **Client ID** and **Client Secret** empty. During authorization, groundcover asks the server to register an OAuth client automatically. * **Pre-registered client**: If the server does not support dynamic client registration, create an OAuth application with the server's provider and enter both its **Client ID** and **Client Secret**. Register these two redirect URLs, replacing the example domain with your groundcover domain: * `https://app.groundcover.com/settings/ai-agents/connectors/mcp/oauth/callback` * `https://app.groundcover.com/connectors/mcp/oauth/callback` The Client ID and Client Secret are a pair. If you enter one, you must enter the other. {% hint style="info" %} OAuth servers must publish compatible authorization metadata. Dynamic registration registers both groundcover redirect URLs automatically; a pre-registered client must allow both URLs before admins and individual users can authorize. {% endhint %} Custom headers are independent of the authentication method and are sent with both token and OAuth requests. {% 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 %} ### Authorize the Admin Connection groundcover uses an admin connection to discover the server's tools and configure organization-wide restrictions: 1. Click **Manage** on an allowlisted Remote MCP Server 2. In the **Tool Restrictions** section: * For a token connector, enter an admin API token. * For an OAuth connector, click **Connect** and complete the provider's authorization flow. 3. After authorization, the full list of available tools appears. {% hint style="info" %} Admin credentials are stored securely. A token can be updated at any time; an OAuth connection can be authorized again if access expires or is revoked. {% endhint %} ### Managing Tool Restrictions 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. Complete the configured authentication flow: * For a token connector, enter your personal API token and click **Connect**. * For an OAuth connector, authorize your account with the external provider. 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 or Reauthorizing Credentials For a token connector, click **Update Token** on the manage page to replace your personal API token. For an OAuth connector, click **Connect** again when groundcover prompts you to reauthorize. ### 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 | Confirm that the admin connection is authorized and that the MCP server is reachable | | Token connection failed | Check that the personal token is valid and that the MCP server is accessible | | OAuth connection failed before consent | Confirm the server publishes OAuth discovery metadata; if it does not support dynamic client registration, recreate the connector with a Client ID and Client Secret | | OAuth callback fails | Confirm the OAuth application's callback URL is correct and that both Client ID and Client Secret belong to the same application | --- # 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=&goal= ``` `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.