> ## 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 MCP servers on developer machines while keeping Runlayer policy, audit, and security controls in the path.

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

```mermaid theme={null}
sequenceDiagram
    participant Client as AI client
    participant CLI as Runlayer CLI on user machine
    participant Cloud as Runlayer
    participant Local as Local MCP server
    participant Upstream as Upstream API or local resource

    Client->>CLI: MCP request over stdio
    CLI->>Cloud: Authenticate, fetch config, check policy
    CLI->>Local: Forward MCP request
    Local->>Upstream: Execute tool
    Upstream-->>Local: Result
    Local-->>CLI: MCP response
    CLI->>Cloud: Audit + security events
    CLI-->>Client: MCP response
```

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

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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>`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Example Client Config

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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```python theme={null}
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 and deploy-backed stdio servers in Runlayer. Local MCPs should use local environment or local config for user-specific secrets.

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Connectors" icon="plug" href="/platform-connectors">
    Add and manage connectors, including local ones
  </Card>

  <Card title="Policies" icon="shield" href="/platform-policies">
    Control access to local connectors and their tools
  </Card>

  <Card title="Custom MCP Servers" icon="cloud-arrow-up" href="/platform-deploy">
    Deploy MCP servers to managed infrastructure instead
  </Card>

  <Card title="MCP Troubleshooting" icon="wrench" href="/mcp-troubleshooting">
    Debug connection, auth, and CLI issues
  </Card>
</CardGroup>