# MCP Gateway ## Overview This guide describes how to add MCP Gateway resources to StrongDM. The Model Context Protocol (MCP) is an open standard that defines how AI agents and large language models interact with external systems in a structured, secure, and auditable way. MCP servers expose capabilities (tools) that agents can discover and invoke. The MCP Gateway resource types allow StrongDM to sit in front of an MCP server as a proxy, requiring authentication depending on the specific resource type chosen. When StrongDM proxies an MCP server, it mediates the requests to the MCP server based on the identity of a user account or principal on whose behalf the request is being made. This gives you centralized credential management, fine-grained authorization policies, and a complete audit trail of every tool invocation. When you add an MCP Gateway resource, StrongDM proxies client connections through a [node](https://docs.strongdm.com/admin/networking) (gateway, relay, or proxy cluster). StrongDM enforces your organization's access policies before any tool call is permitted, and then authenticates requests to the MCP server using the provided OAuth credentials. For general information about how to add a datasource in StrongDM, see [Add a Datasource](https://docs.strongdm.com/admin/resources/datasources). ## Use Cases The MCP Gateway resource type is suited for the following scenarios: * **Desktop AI agent orchestration:** Teams that are using Desktop AI agents need governed, auditable access to external services (such as GitHub) via MCP. * **Centralized MCP access control:** Organizations want a single control plane to manage which agents and users can invoke which MCP tools, using StrongDM roles and policies rather than per-server configuration. * **Compliance and auditing:** Regulated environments require an audit log of every MCP tool invocation. {% hint style="info" %} **DCR Support** Some MCP servers do not support Dynamic Client Registration (DCR). As a result, clients such as Claude cannot normally use OAuth to connect to those servers directly. The StrongDM MCP Gateway (OAuth) resource type provides its own implementation of DCR and bridges this gap, enabling OAuth-based connections to MCP servers that do not natively support DCR. {% endhint %} ## Prerequisites To add an MCP Gateway resource in StrongDM, ensure that the following requirements are met. ### Client requirements The end user must be using a supported Desktop AI agent: * Claude Code * Claude Desktop * Codex CLI * Copilot (in VS Code) ### StrongDM requirements In StrongDM, you must have the following: * Administrator permission level * At least one operational StrongDM node (gateway, relay, or proxy cluster) with network access to the target MCP server hostname and port * If storing OAuth credentials in an external secrets manager, a Secret Store configured in StrongDM under **Settings** > **Secrets Management** * Should be using CLI version 53.66.0 or higher {% hint style="info" %} To verify that the MCP server is reachable from your StrongDM node, log in to the gateway or relay and use Netcat: `nc -zv `. If the connection succeeds, your node can reach the MCP server and you may proceed. {% endhint %} ### MCP server requirements There is information you need to provide from your MCP server. Choose the tab below for the specific resource type you are using, based on how you intend to authenticate traffic to the MCP server. {% tabs %} {% tab title="OAuth" %} To set up an MCP Gateway (OAuth) resource, you need the **MCP Server URL** value from your MCP server (for example, `https://api.githubcopilot.com/v1`) that is reachable from your StrongDM node. You also need the following values from the authentication server that is configured to authenticate traffic to your MCP server (for example, a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)): * **Client ID** and **Client Secret** for the OAuth application * **OAuth Authorization Endpoint URL** for the OAuth application * **OAuth Token Endpoint URL** for the OAuth application * **OAuth Scopes** that should be used during connections Lastly, your OAuth app's redirect URI should be set to the StrongDM OAuth callback URL that matches the region of your organization's control plane: * `https://app.strongdm.com/oauth/callback` (for US) * `https://app.uk.strongdm.com/oauth/callback` (for UK) * `https://app.eu.strongdm.com/oauth/callback` (for EU) {% endtab %} {% tab title="Personal Access Token" %} To set up an MCP Gateway (PAT) resource, you need the following values from your MCP server: * **MCP Server URL** (for example, `https://api.githubcopilot.com/v1`) that is reachable from your StrongDM node * **Personal Access Token** that you intend to use for authentication. This is a common user API token. **Example:** For GitHub MCP servers, your GitHub API token can be created and copied from your [GitHub Account Settings](https://github.com/settings/personal-access-tokens). {% endtab %} {% tab title="No Auth" %} To set up an MCP Gateway (NoAuth) resource, you need the **MCP Server URL** value (for example, `https://api.githubcopilot.com/v1`) from your MCP server that is reachable from your StrongDM node. {% endtab %} {% endtabs %} ## Limitations Be aware of the following limitations when using the MCP Gateway resource types: * **Choose the right resource type**: StrongDM offers specific resource types for MCP gateways. If your MCP only has one modality (Requires OAuth, only provides PATs, or has no auth) choose the corresponding resource type. If it supports several, you may select the one that best fits your use case: * MCP Gateway (OAuth) for authenticating with an OAuth app. OAuth apps allow the end users to authenticate as themselves, receiving the same permissions on the MCP server that they already have. * MCP Gateway (PAT) for authenticating with a personal access token. PATs provide the ability for admins to set up resources with scoped tokens, providing fine-grained control over what users of that resource access, but all users of the server would have the same access, and native logging on the MCP server side would not differentiate between the actions of specific users. * MCP Gateway (NoAuth) for connections without authentication, such as to servers that are on internal networks or are otherwise access-restricted. * **MCP-over-HTTP only**: StrongDM's MCP Gateway proxies streamable HTTP MCP servers. Local stdio-based MCP servers (for example, servers started as child processes via `npx` or `uvx`) are not supported. * **Tool-level policy enforcement**: Fine-grained Cedar-based policies on individual MCP tool actions (for example, permitting `calendar.getEvents` but denying `calendar.deleteEvent`) require additional [policy configuration](https://github.com/strongdm/docs/blob/main/gitbook-content/admin/resources/datasources/mcp-gateway-oauth.md#restrict-tools-with-policies) in StrongDM beyond resource creation. Creating the resource alone does not restrict tool-level actions. * **Single upstream host per resource**: Each MCP Gateway resource proxies one upstream MCP server hostname. To proxy multiple MCP servers, create a separate resource in StrongDM for each. * **Auth Flows**: The MCP Gateway (OAuth) resource type supports only the `authorization_code` grant type with PKCE and the refresh token flow. Ensure these flows are enabled when configuring the OAuth application. ## Resource Management in StrongDM After all prerequisites are met, you are ready to add the resource to StrongDM. This section provides instructions for adding the resource in either the StrongDM Admin UI or the CLI. {% tabs %} {% tab title="Admin UI" %} **Set up and manage with the Admin UI** If using the Admin UI to add an MCP Gateway resource, use the following steps. 1. Log in to the StrongDM Admin UI. 2. Go to **Resources** > **Managed Resources**. 3. Click **Add Resource**, and give it a **Name**. 4. Select a **Resource Type**: **MCP Gateway (OAuth)**, **MCP Gateway (PAT)**, or **MCP Gateway (NoAuth)**. 5. Complete all required fields. See [Configuration Properties](https://github.com/strongdm/docs/blob/main/gitbook-content/admin/resources/datasources/mcp-gateway-oauth.md#configuration-properties) for a description of each field. 6. Click **Create** to save the resource. 7. Click the resource name to view status, diagnostic information, and setting details. After saving, StrongDM attempts a healthcheck against the MCP server. The resource status displays as unhealthy until the first successful healthcheck completes. When the resource is ready, the **Health** icon turns green. {% endtab %} {% tab title="CLI" %} **Set up and manage with the CLI** This section provides an example of how to add an MCP Gateway (OAuth) resource using the StrongDM CLI. For more information and examples, see the [CLI Reference](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli) documentation. 1. In your terminal, log in to StrongDM: ```sh sdm login ``` 2. Run the `sdm admin datasources add mcp` command with a help flag to view the help text, which shows all available options and which fields are required. ```sh sdm admin datasources add mcp --help ``` 3. Run `sdm admin datasources add mcp ` with all required flags to create the resource. For example: ```sh sdm admin datasources add mcp "github-mcp-prod" \ --url "https://api.githubcopilot.com/mcp/" \ --client-id "0oa1b2c3d4e5f6g7h8i9" \ --client-secret "your-client-secret-value" \ --oauth-auth-endpoint "https://your-idp.example.com/oauth2/v1/authorize" \ --oauth-token-endpoint "https://your-idp.example.com/oauth2/v1/token" \ --bind-interface "default" \ --port-override -1 \ --egress-filter "tag:env=prod" \ --proxy-cluster-id "plc_0123456789abcdef" \ --secret-store-id "ss_abcdef0123456789" \ --subdomain "github-mcp-prod" \ --tags "env=prod,team=platform,type=mcp" ``` 4. Verify the resource was created successfully: ```sh sdm admin resources list ``` The output should include the name of your newly created MCP Gateway resource. {% endtab %} {% tab title="Terraform" %} **Set up and manage with Terraform** This section provides an example of how to configure and manage an MCP Gateway (OAuth) resource using the Terraform provider. For more information and examples, see the [Terraform provider](https://github.com/strongdm/terraform-provider-sdm) documentation. ```hcl # Install StrongDM provider terraform { required_providers { sdm = { source = "strongdm/sdm" version = "16.20.0" } } } # Configure StrongDM provider provider "sdm" { api_access_key = "njjSn...5hM" api_secret_key = "ziG...=" } # Create MCP Gateway (OAuth) datasource resource "sdm_resource" "github_mcp_prod" { mcp { # Required name = "github-mcp-prod" url = "https://api.githubcopilot.com/mcp/" client_id = "0gt1bbc10g65f6g7h8k9" client_secret = "your-client-secret-value" oauth_auth_endpoint = "https://your-idp.example.com/oauth2/v1/authorize" oauth_token_endpoint = "https://your-idp.example.com/oauth2/v1/token" # Networking / routing bind_interface = "default" port_override = -1 egress_filter = "tag:env=prod" proxy_cluster_id = "plc_0123456789abcdef" subdomain = "github-mcp-prod" # Secrets / metadata secret_store_id = "ss_abcdef0123456789" tags = { env = "prod" team = "platform" type = "mcp" } } } ``` {% endtab %} {% tab title="SDKs" %} **Set up and manage with SDKs** In addition to the Admin UI, CLI, and Terraform, you may configure and manage your resource with any of the following SDK options: Go, Java, Python, and Ruby. See the following references for more information and examples. | Language | Reference | GitHub | Examples | | ------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | Go | [pkg.go.dev](https://pkg.go.dev/github.com/strongdm/strongdm-sdk-go/v16) | [strongdm-sdk-go](https://github.com/strongdm/strongdm-sdk-go) | [Go SDK Examples](https://github.com/strongdm/strongdm-sdk-go-examples) | | Java | [javadoc](https://strongdm.github.io/strongdm-sdk-java-docs/) | [strongdm-sdk-java](https://github.com/strongdm/strongdm-sdk-java) | [Java SDK Examples](https://github.com/strongdm/strongdm-sdk-java-examples) | | Python | [pdocs](https://strongdm.github.io/strongdm-sdk-python-docs/) | [strongdm-sdk-python](https://github.com/strongdm/strongdm-sdk-python) | [Python SDK Examples](https://github.com/strongdm/strongdm-sdk-python-examples) | | Ruby | [RubyDoc](https://www.rubydoc.info/gems/strongdm) | [strongdm-sdk-ruby](https://github.com/strongdm/strongdm-sdk-ruby) | [Ruby SDK Examples](https://github.com/strongdm/strongdm-sdk-ruby-examples) | | {% endtab %} | | | | | {% endtabs %} | | | | ## Configuration Properties ### Resource Properties These are the properties available to all MCP Gateway resource types. | Property | Requirement | Description | | --------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Display Name** | Required | Meaningful name to display the resource throughout StrongDM; exclude special characters like quotes (") or angle brackets (< or >) | | **Resource Type** | Required | **MCP Gateway (OAuth)** | | **Proxy Cluster** | Required | Defaults to "None (use gateways)"; if using [proxy clusters](https://docs.strongdm.com/admin/networking/proxy-clusters), select the appropriate cluster to proxy traffic to this resource | | **MCP Server URL** | Required | Hostname or IP address of the upstream MCP server (for example, `https://api.githubcopilot.com/mcp/`); the StrongDM node must be able to reach this host | | **Connectivity Mode** | Required | Select either **Virtual Networking Mode**, which lets users connect to the resource with a software-defined, IP-based network; or **Loopback Mode**, which allows users to connect to the resource using the local loopback adapter in their operating system; this field is shown if [Virtual Networking Mode](https://docs.strongdm.com/admin/clients/client-networking/virtual-networking-mode) is enabled for your organization | | **IP Address** | Optional | If **Virtual Networking Mode** is the selected connectivity mode, an IP address value in the configured Virtual Networking Mode subnet; if **Loopback Mode** is selected, an IP address value in the configured Loopback IP range (by default, `127.0.0.1`); if not specified, an available IP address is automatically assigned; this field is shown if [Virtual Networking Mode](https://docs.strongdm.com/admin/clients/client-networking/virtual-networking-mode) and/or [multi-loopback mode](https://docs.strongdm.com/admin/clients/client-networking/loopback-ip-ranges) is enabled for your organization | | **Port Override** | Optional | If **Virtual Networking Mode** is selected, a port value between 1 and 65535 not already in use by another resource with the same IP address; if **Loopback Mode** is selected, a port value between 1024 and 64999 not already in use; when left empty, an available port is automatically assigned; can also be modified later from [Port Overrides settings](https://docs.strongdm.com/admin/resources/port-overrides); specify `-1` in the CLI to auto-allocate | | **DNS** | Optional | If Virtual Networking Mode is selected, a unique hostname alias for this resource; when set, the desktop app displays this resource's human-readable DNS name instead of the raw IP address and port | | **Secret Store** | Optional | Credential store location for the Client Secret; defaults to none (credentials stored in StrongDM); to learn more, see [Secret Store options](#secret-store-options) | | **Resource Tags** | Optional | Resource [Tags](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/tags) consisting of key-value pairs `=` (for example, `env=prod`) | ### Resource Type Specific Fields There are a few additional fields that are unique to the **MCP Gateway (OAuth)** and **MCP Gateway (PAT)** resource types. {% tabs %} {% tab title="MCP Gateway (OAuth)" %} | Property | Requirement | Description | | ------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OAuth App Client ID** | Required | OAuth client ID issued by your authorization server for the registered application that represents this MCP server integration | | **OAuth App Client Secret** | Required | OAuth client secret corresponding to the Client ID; treated as a sensitive credential and stored encrypted within StrongDM or your configured Secret Store | | **OAuth Authorization Endpoint URL** | Required | Full URL of the OAuth 2.1 authorization endpoint on your identity provider (for example, `https://your-idp.example.com/oauth2/v1/authorize`) | | **OAuth Token Endpoint URL** | Required | Full URL of the OAuth 2.1 token endpoint on your identity provider (for example, `https://your-idp.example.com/oauth2/v1/token`) | | **OAuth Scopes** | Optional | Any specific OAuth scopes that should be used during connections | | {% endtab %} | | | {% tab title="MCP Gateway (PAT)" %} | Property | Requirement | Description | | ------------------------- | ----------- | ----------------------------- | | **Personal Access Token** | Required | An access token for your user | | {% endtab %} | | | | {% endtabs %} | | | ### Secret Store options By default, datasource credentials (including the OAuth Client Secret) are stored in StrongDM. However, these credentials can also be stored in a secrets management tool such as HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault. Non-StrongDM Secret Store options appear in the **Secret Store** dropdown if they are created under **Settings** > **Secrets Management**. When you select an external Secret Store type, its unique path and key properties display in the form. For more details, see the [Secret Stores](https://docs.strongdm.com/admin/access/secret-stores) documentation. ### Resource status After a resource is created, the Admin UI displays that resource as unhealthy until the healthchecks run successfully. When the resource is ready, the **Health** icon indicates a positive, green status. When the resource does not display a positive status, click the resource name to go to the **Diagnostics** tab and review any errors. ## Add the MCP Server to Your Desktop AI Agent {% tabs %} {% tab title="Claude Code" %} Run the following command, where "TestGitHub" is the name you'd like to give to the MCP Server accessed via StrongDM, and 127.0.0.1:10001 is the IP and port assigned to your MCP Gateway resource by StrongDM: ```sh claude mcp add --transport http TestGitHub http://127.0.0.1:10001 ``` Once this is done, you need to close the current session, open a new session and then issue an `/mcp` command. Pick `TestGitHub` from the list, then choose **Authenticate**, which should authenticate using your GitHub account. In some cases, you may get a connection message that indicates you need to restart again after authenticating. {% endtab %} {% tab title="Claude Desktop" %} 1. Locate the configuration file `claude_desktop_config.json` (if it doesn't exist, create it): * **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json` * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` 2. Edit the `claude_desktop_config.json` file. Open the file in a text editor and add your server configuration. Example: ```json { "mcpServers": { "TestGitHub": { "type": "http", "url": "http://127.0.0.1:10001" } } } ``` {% endtab %} {% tab title="Codex CLI" %} Run the following command, where "TestGitHub" is the name you'd like to give to the MCP Server accessed via StrongDM, and 127.0.0.1:10001 is the IP and port assigned to your MCP Gateway resource by StrongDM: ```sh codex mcp add TestGitHub --url http://127.0.0.1:10001 ``` Once this is done, you need to close the current session, open a new session and then issue an `/mcp` command. Pick `TestGitHub` from the list, then choose **Authenticate**, which should authenticate using your GitHub account. In some cases, you may get a connection message that indicates you need to restart again after authenticating. {% endtab %} {% tab title="Copilot in VS Code" %} You can manually configure MCP servers in VS Code by editing the `mcp.json` file, which can be placed in one of two locations: * In your project: Create or open `.vscode/mcp.json` in your project. This is where MCP servers can be configured for use just in this project. This file can also be included in source control to share the configuration with teammates. * In your user profile: Run the **MCP: Open User Configuration** command in the Command Palette (⇧⌘P) to open the `mcp.json` file in your user profile folder. Servers configured here are available across all your workspaces and projects. You can also run **MCP: Add Server** command in the Command Palette (⇧⌘P) to add a server through a guided flow, choosing either **Workspace** or **Global** as the target. Then, add an entry for the MCP Gateway resource, where "TestGitHub" is the name you'd like to give to the MCP Server accessed via StrongDM, and 127.0.0.1:10001 is the IP and port assigned to your MCP Gateway resource by StrongDM: ```json { "servers": { "TestGitHub": { "type": "http", "url": "http://127.0.0.1:10001" } } } ``` You should now be able to query the MCP server now via agents in VS Code. {% endtab %} {% endtabs %} ## Test the Connection After adding the resource, follow these steps to verify that it is working correctly. 1. Assign access by ensuring your user or role has access to the resource. In the StrongDM Admin UI, go to **Access** > **Roles**, and verify that the resource is attached to a role you are a member of. 2. In the CLI, run `sdm status` to list your accessible resources and confirm the MCP Gateway resource appears. 3. Initiate a connection to the resource: ```sh sdm connect github-mcp-prod ``` 4. If you have not already done so, add the MCP Gateway as an MCP server in your supported Desktop AI agent as shown in the [Add the MCP Server to Your Desktop AI Agent](#add-the-mcp-server-to-your-desktop-ai-agent) section. 5. Once the MCP server has been added and the tool restarted or a new session opened, you can attempt to use a GitHub tool via the MCP server using your Desktop AI Agent. Example: "get my GitHub profile using mcp". For MCP servers such as GitHub that require authentication, you may be prompted to authenticate with your user credentials on first use. 6. Once you are successfully doing MCP tool calls through StrongDM, go to the StrongDM Admin UI and check **Logs** > **Activities** to confirm the session is logged, and **Logs** > **Queries** to see any tool invocations that were recorded. ## Restrict Tools With Policies It is also possible to restrict the specific tools that are available to a user and their agent based on policies. For example, in the following policy, the tool "new\_issue" is restricted, with an error message. ```cedar @error("Our Organization does not allow AI Agents to create new issues.") forbid ( principal, action == MCP::Action::"new_issue", resource in StrongDM::Resource::"rs-602d0a1f68bee5c7" ); ``` There is no autocomplete in the policy editor for tool names, nor is there any standard list of tool names. Tool names are unique to each MCP server. Admins writing policies for tool restriction need to know the names of the tools and to match those tool names exactly. For example, if the tool name is "new\_issue" and the admin writes "new-issue" or "new issue", the policy does not match against the actual tool call. You can get the names of tools by listing available tools from the connected MCP server in your Desktop AI agent, from StrongDM query logs if the tools have already being used, or from the docs for your MCP server. {% hint style="info" %} The tool sets available for MCP servers can change when the vendors update their MCP server capabilities. If you are attempting to restrict tools available to users, policies should be written with this in mind, and reviewed regularly. {% endhint %} ## Troubleshooting ### Resource shows as unhealthy after creation After creating the resource, StrongDM performs an automatic healthcheck against the upstream MCP server. If this fails, the resource remains unhealthy. Common causes and resolutions are listed below. | Error or Symptom | Likely Cause | Resolution | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Resource stays unhealthy after creation | The StrongDM node cannot reach the MCP server hostname. | Verify network connectivity from the node to the hostname and port using `nc -zv `; check firewall rules and security groups. | | `401 Unauthorized` errors in Diagnostics | OAuth credentials are invalid or the token endpoint URL is incorrect. | Verify the Client ID, Client Secret, and token endpoint URL match exactly what your OAuth provider issued; test the token endpoint directly with `curl`. | | `invalid_client` or `unauthorized_client` from OAuth provider | The OAuth application is not authorized for the configured scopes or grant types. | Review your OAuth app's configuration in the identity provider; ensure the Client Credentials or Authorization Code grant type is enabled. | | Connection succeeds but tools list is empty | The upstream MCP server is reachable but `tools/list` returned no tools. | Verify the MCP server is running and properly serving tools; connect directly to the MCP server (bypassing StrongDM) to confirm `tools/list` returns results. | | `invalid redirect_uri` during OAuth flow | The redirect URI configured in the OAuth provider does not match StrongDM's callback. | Update the redirect URI in your OAuth application to match the StrongDM-provided callback URL shown in the Admin UI. | | Users cannot see the resource in their client | Access has not been granted. | Go to **Access** > **Roles** in the Admin UI and ensure the resource is attached to a role that the user is a member of. | | Users of Claude Desktop see "This site can't be reached" after OAuth transactions | Outdated StrongDM version has a response timing issue | Restart Claude Desktop, then confirm the MCP Gateway is running in **Settings** > **Developer** > **Local MCP Servers**. Later versions of StrongDM solve this issue. | ### OAuth token expiry and refresh If users experience unexpected disconnections or `401` errors during an active session, the OAuth access token may have expired. Ensure that the token endpoint supports token refresh and that the Client Secret is valid. If using a short-lived token policy, consider adjusting the session duration in your identity provider. ### Still encountering issues? If you continue to experience problems, consult the [StrongDM Help Center](https://help.strongdm.com/hc/en-us) or contact StrongDM Support. When reaching out, provide the following to help the support team diagnose the issue: * Resource name or ID * CLI error output or logs from `sdm status` * Node (gateway or relay) logs * Output of `sdm admin resources list` showing the resource's health state