Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt

Use this file to discover all available pages before exploring further.

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
  • A local HTTP/SSE MCP endpoint already running on localhost
  • A verified local application connector, such as a desktop app integration

​
Set Up a Local MCP

1

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 local URL, for example http://127.0.0.1:3333/mcp.
2

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

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

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.

​
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 inherits environment variables from the runlayer run process. A client config can pass a user-specific token like this: 
{
  "mcpServers": {
    "my-local-mcp": {
      "command": "runlayer",
      "args": [
        "run",
        "<RUNLAYER_SERVER_ID>",
        "--host",
        "https://<tenant>.runlayer.com"
      ],
      "env": {
        "UPSTREAM_TOKEN": "<user-specific-token>"
      }
    }
  }
}
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 in the MCP config. An empty value can override the user’s shell environment and cause the local MCP to receive an empty 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.

​
What Runlayer Sees

Runlayer receives:
  • The authenticated Runlayer user
  • Connector and tool metadata
  • Policy decisions
  • Tool call audit events
  • ToolGuard security scan results
Runlayer does not need to store local upstream tokens for this flow. A local upstream token can stay on the user’s machine and be used only by the local MCP.

​
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 on the machine where the AI client runs.
  • For stdio MCPs, user-specific environment variables can be provided through the client config or shell environment.
  • For local HTTP/SSE MCPs, start the local server with its required environment before the AI client connects.
  • Runlayer-managed per-user placeholder values are for HTTP/SSE connectors in Runlayer. Local MCPs should use local environment or local config for user-specific secrets.