MCP Gateway

Use the MCP Gateway resource types to proxy Model Context Protocol (MCP) servers through StrongDM, enabling centralized access control, auditing, and policy enforcement for Desktop AI agent workloads.

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

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.

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.

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)
Kiro

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

To verify that the MCP server is reachable from your StrongDM node, log in to the gateway or relay and use Netcat: nc -zv <HOSTNAME> <PORT>. If the connection succeeds, your node can reach the MCP server and you may proceed.

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.

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):

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)

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

Set up and manage with the Admin UI

If using the Admin UI to add an MCP Gateway resource, use the following steps.

Log in to the StrongDM Admin UI.
Go to Resources > Managed Resources.
Click Add Resource, and give it a Name.
Select a Resource Type: MCP Gateway (OAuth), MCP Gateway (OAuth with DCR), MCP Gateway (PAT), or MCP Gateway (NoAuth).
Complete all required fields. See Configuration Properties for a description of each field.
Click Create to save the resource.
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.

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. Follow this general example to add the other MCP Gateway resource types, which are not shown in the following example. For more information and examples, see the CLI Reference documentation.

In your terminal, log in to StrongDM:
```
sdm login
```
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.
```
sdm admin datasources add mcp --help
```

Run sdm admin datasources add mcp <RESOURCE_NAME> with all required flags to create the resource. For example:

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"

Verify the resource was created successfully:
```
sdm admin resources list
```
The output should include the name of your newly created MCP Gateway resource.

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

# 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"
    }
  }
}

# Create MCP Gateway (OAuth with DCR) datasource
resource "sdm_resource" "github_mcp_dcr_prod" {
  mcp_dcr {
    # Required
    name                    = "github-mcp-dcr-prod"
    url                     = "https://api.githubcopilot.com/mcp/"
    oauth_auth_endpoint     = "https://your-idp.example.com/oauth2/v1/authorize"
    oauth_register_endpoint = "https://your-idp.example.com/oauth2/v1/register"
    oauth_token_endpoint    = "https://your-idp.example.com/oauth2/v1/token"

    # Optional OAuth settings
    oauth_scopes = "openid profile email"

    # Networking / routing
    bind_interface   = "default"
    port_override    = -1
    egress_filter    = "tag:env=prod"
    proxy_cluster_id = "plc_0123456789abcdef"
    subdomain        = "github-mcp-dcr-prod"

    # Metadata
    tags = {
      env  = "prod"
      team = "platform"
      type = "mcp"
    }
  }
}

# Create MCP Gateway (PAT) datasource
resource "sdm_resource" "github_mcp_pat_prod" {
  mcp_pat {
    # Required
    name  = "github-mcp-pat-prod"
    url   = "https://api.githubcopilot.com/mcp/"
    token = "your-personal-access-token"

    # Networking / routing
    bind_interface   = "default"
    port_override    = -1
    egress_filter    = "tag:env=prod"
    proxy_cluster_id = "plc_0123456789abcdef"
    subdomain        = "github-mcp-pat-prod"

    # Secrets / metadata
    secret_store_id = "ss_abcdef0123456789"
    tags = {
      env  = "prod"
      team = "platform"
      type = "mcp"
    }
  }
}

# Create MCP Gateway (NoAuth) datasource
resource "sdm_resource" "github_mcp_noauth_prod" {
  mcp_no_auth {
    # Required
    name = "github-mcp-noauth-prod"
    url  = "https://api.githubcopilot.com/mcp/"

    # Networking / routing
    bind_interface   = "default"
    port_override    = -1
    egress_filter    = "tag:env=prod"
    proxy_cluster_id = "plc_0123456789abcdef"
    subdomain        = "github-mcp-noauth-prod"

    # Metadata
    tags = {
      env  = "prod"
      team = "platform"
      type = "mcp"
    }
  }
}

Configuration Properties

Resource Properties

These are the general properties that are available to the 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, 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 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 and/or multi-loopback mode 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; 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

Resource Tags

Optional

Resource Tags consisting of key-value pairs <KEY>=<VALUE> (for example, env=prod)

Resource Type Specific Fields

There are a few additional fields that are unique to the MCP Gateway (OAuth), MCP Gateway (PAT), and MCP Gateway (OAuth with DCR) resource types.

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

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

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:

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.

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

Edit the claude_desktop_config.json file. Open the file in a text editor and add your server configuration. Example:

{
  "mcpServers": {
    "TestGitHub": {
      "type": "http",
      "url": "http://127.0.0.1:10001"
    }
  }
}

codex mcp add TestGitHub --url http://127.0.0.1:10001

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:

{
  "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.

You can configure the MCP server at either the workspace level (.kiro/settings/mcp.json) or the user level (~/.kiro/settings/mcp.json). Workspace settings apply only to the current project, whereas user-level settings apply globally. If both exist, workspace settings take precedence.

If using the command palette, follow these steps:
a. Open the command palette:
- Mac: Cmd + Shift + P
- Windows/Linux: Ctrl + Shift + P
1. Search for "MCP" and select:
  - Kiro: Open workspace MCP config (JSON) – for project-level configuration
  - Kiro: Open user MCP config (JSON) – for global configuration
If using the Kiro panel, follow these steps:
1. Open the Kiro panel.
2. Select the Open MCP Config icon.
In whichever file you open, 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:

{
  "mcpServers": {
    "TestGitHub": {
      "url": "http://127.0.0.1:10001"
    }
  }
}

Save the file (Cmd+S / Ctrl+S). Kiro automatically reconnects MCP servers when the config is saved.

Test the Connection

After adding the resource, follow these steps to verify that it is working correctly.

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.
In the CLI, run sdm status to list your accessible resources and confirm the MCP Gateway resource appears.
Initiate a connection to the resource:
```
sdm connect github-mcp-prod
```
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 section.
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.
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.

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

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.

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 <hostname> <port>; 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 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

Last updated 1 month ago

Was this helpful?