Local MCPs

Local MCPs run on a user’s machine, but the AI client does not call them directly. The client launches the Runlayer CLI as a local MCP process, and the CLI proxies requests to the real local MCP server. This keeps local execution local while still applying Runlayer access control, policy checks, ToolGuard scanning, and audit logging.

How It Works

From the AI client’s perspective, runlayer run <server-id> is the MCP server. From Runlayer’s perspective, the CLI is the controlled proxy for the local MCP. The real local MCP can be:

A stdio process started by the Runlayer CLI, such as npx, uvx, or a local binary
An HTTP/SSE MCP endpoint reachable from the user’s machine, on localhost or a private network/VPN
A verified local application connector, such as a desktop app integration

Set Up a Local MCP

Create or select a local connector

In Runlayer, add a local connector from the catalog or create one manually.For stdio, configure the command, arguments, and any shared environment variables the MCP needs.For local HTTP/SSE, configure the upstream URL, for example http://127.0.0.1:3333/mcp. Add any shared upstream credentials in the connector’s Headers field (see HTTP headers).

Assign access

Add the connector to the right users or groups and configure policies as usual.Local connectors use the same policy model as hosted connectors.

Install into the AI client

From the connector page, use the client setup instructions, or run the Runlayer setup command for the client.The installed MCP entry points the client at runlayer run <server-id>.

Run the client

When the AI client starts the MCP server, it launches the Runlayer CLI locally. The CLI authenticates to Runlayer, starts or connects to the local MCP target, and proxies tool calls.

Example Client Config

Most users should install local MCPs from the Runlayer UI or setup command. A minimal MCP client entry looks like this:

{
  "mcpServers": {
    "my-local-mcp": {
      "command": "runlayer",
      "args": [
        "run",
        "<RUNLAYER_SERVER_ID>",
        "--host",
        "https://<tenant>.runlayer.com"
      ]
    }
  }
}

If the user has not logged in yet, run:

runlayer login --host https://<tenant>.runlayer.com

You can pass --secret <RUNLAYER_USER_TOKEN> explicitly, but runlayer login is preferred for normal user setup.

Headers for Local HTTP MCPs

For local Streaming HTTP or SSE connectors, enter literal upstream header values in the connector’s Headers field in Runlayer. The CLI sends them when connecting to the upstream MCP server.

Header	Example value
`Authorization`	`Basic <base64-encoded username:password>`
`X-API-Key`	`your-upstream-api-key`

A configured Authorization header disables automatic OAuth discovery. Explicitly configured OAuth, manual OAuth setup, and OAuth Broker flows still apply. Configured headers stay scoped to the upstream origin (scheme, hostname, and port). Redirects to a different origin do not receive them. Runlayer stores these header values and sends them to the CLI for the connector. Use shared credentials suitable for the users and devices connecting locally. Local connectors require literal values; Runlayer placeholders such as {API_KEY} are unsupported. For user-specific secrets, use the local server’s environment or configuration.

This requires a CLI release that includes local HTTP header forwarding. Older CLI releases ignore configured HTTP headers; updating the Runlayer backend alone does not update the CLI on users’ machines. See Runlayer CLI for installation and fleet updates.

User-Specific Local Secrets

Local MCPs often need a token for an upstream service. Keep that token local to the user’s machine. For stdio MCPs launched by Runlayer, the local MCP receives only the connector’s configured environment variables (set on the connector in Runlayer) plus a small proxy/TLS/locale allowlist from the surrounding environment — not the full runlayer run environment. An admin can also name specific variables to pass through from the user’s environment via the connector’s Inherit from the user’s environment setting (transport_config.inherit_env). Only the names are stored; values are never sent to Runlayer and are passed only to the local MCP process, and a value set in the connector’s env still wins. Set the upstream token as an environment variable on the connector in Runlayer; values placed in the AI client’s env block reach runlayer run but are not forwarded to the local MCP unless an admin lists them there. The MCP code can then read it normally:

import os
import httpx

token = os.environ["UPSTREAM_TOKEN"]

response = httpx.get(
    "https://upstream.example.com/api",
    headers={"Authorization": f"Bearer {token}"},
)

Do not set the token to an empty value on the connector; an empty string is still forwarded to the local MCP, leaving it without a token. For local HTTP/SSE MCPs that are already running on localhost, set the token in the environment of that local server process before it starts. Setting an environment variable on runlayer run will not change the environment of a separate process that is already running.

Troubleshooting

IdPs with exact redirect URI allowlists (e.g. Okta)

For local HTTP/SSE MCP OAuth, use a fixed callback port:

runlayer cache clear
runlayer run <RUNLAYER_SERVER_ID> --host https://<tenant>.runlayer.com --oauth-callback-port <port>

Or set RUNLAYER_OAUTH_CALLBACK_PORT=<port>. Allowlist http://localhost:<port>/callback in the IdP. Clear the cache first if a previous random-port attempt cached a client registration.

What Runlayer Sees

Runlayer receives:

The authenticated Runlayer user
Connector and tool metadata
Policy decisions
Tool call audit events
ToolGuard security scan results

For local HTTP/SSE MCPs, secrets configured only in the upstream server’s environment or configuration stay with that server and are not stored by Runlayer. Headers entered in the Runlayer connector configuration are stored by Runlayer and sent to the CLI. For stdio MCPs, set the upstream token as an environment variable on the connector in Runlayer.

Caveats

Local MCPs require the Runlayer CLI to be installed on the user’s machine.
Users must be authenticated with runlayer login or an explicit Runlayer user token.
The local MCP target must be available or reachable from the machine where the AI client runs.
For stdio MCPs, environment variables for the local MCP must be set on the connector in Runlayer; the surrounding shell environment is not inherited beyond a small proxy/TLS/locale allowlist and any variable names an admin lists under the connector’s Inherit from the user’s environment setting (transport_config.inherit_env). Names only — values are never sent to Runlayer and are passed only to the local MCP process, and the connector’s env wins on conflict.
For local HTTP/SSE MCPs, ensure the upstream is reachable before the AI client connects. For a server running on the user’s machine, start it with its required environment.
Runlayer-managed per-user placeholder values are for hosted HTTP/SSE connectors and deploy-backed stdio servers in Runlayer. Local HTTP/SSE connectors require literal headers and can use the local server process’s environment or local config for user-specific secrets.

Connectors

Add and manage connectors, including local ones

Policies

Control access to local connectors and their tools

Custom MCP Servers

Deploy MCP servers to managed infrastructure instead

MCP Troubleshooting

Debug connection, auth, and CLI issues

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

How It Works

Set Up a Local MCP

Example Client Config

Headers for Local HTTP MCPs

User-Specific Local Secrets

Troubleshooting

IdPs with exact redirect URI allowlists (e.g. Okta)

What Runlayer Sees

Caveats

Connectors

Policies

Custom MCP Servers

MCP Troubleshooting

​How It Works

​Set Up a Local MCP

​Example Client Config

​Headers for Local HTTP MCPs

​User-Specific Local Secrets

​Troubleshooting

​IdPs with exact redirect URI allowlists (e.g. Okta)

​What Runlayer Sees

​Caveats

​Related Resources

Connectors

Policies

Custom MCP Servers

MCP Troubleshooting

How It Works

Set Up a Local MCP

Example Client Config

Headers for Local HTTP MCPs

User-Specific Local Secrets

Troubleshooting

IdPs with exact redirect URI allowlists (e.g. Okta)

What Runlayer Sees

Caveats

Related Resources