Skip to main content
When you connect an AI client (Claude, ChatGPT, Cursor, VS Code, an agent framework, etc.) to Runlayer, you point it at a Runlayer proxy endpoint. Every request to that endpoint is authenticated, policy-checked, scanned by ToolGuard, and audit-logged before it reaches the upstream MCP server. There are two connection models, and a common question on rollout is “do we give people one unified Runlayer URL, or a separate URL per MCP server?” This page explains both and when to use each.

The two connection models

Both models enforce the same controls. The unified endpoint does not grant any extra access — it only surfaces connectors, skills, and tools the user already has through policy. Direct connector calls and execute_tool calls both run through the underlying connector’s normal PBAC, ToolGuard, OAuth/session, and audit-log checks.

When to use the unified endpoint (Runlayer Plugin)

Runlayer Plugin is the recommended default for most organizations. Use it when you want:
  • One thing to install. Users add a single MCP connection and immediately get every tool they’re entitled to — no per-connector setup, no client sprawl.
  • Tool discovery matched to the client. When flat routing is enabled, supported clients with native tool discovery can receive connector tools directly. Other clients use search_tools to find the right tool, then execute_tool to run it.
  • Standardized rollout. Admins push Runlayer Plugin through Auto-Sync, an Anthropic org install, or an OpenAI org install.
  • Policy-aware access that updates itself. When you change a policy or grant, the user’s available tools change on their next request — no client reconfiguration.
Runlayer Plugin exposes active, hosted connectors only. It does not expose local (CLI-run) connectors, draft or disabled connectors, or tools blocked by policy for that user.

When to use an individual connector endpoint

Connect a client directly to a single connector’s MCP URL when:
  • A client or agent needs one specific connector with a fixed, narrow tool list rather than the organization’s unified surface.
  • You’re connecting a local MCP that runs on the user’s machine behind the Runlayer CLI. Local connectors are not part of Runlayer Plugin, so they always use their own connection.
  • You’re integrating an SDK or agent framework that expects a concrete MCP server URL and a fixed tool list. See Agent Frameworks.
  • You’re protecting an MCP server you publish to others (customers/partners). Each consumer connects to that server’s Runlayer endpoint.
You can mix both models: give most users Runlayer Plugin as the default, while a specific agent or power user connects directly to an individual connector.

Where the Runlayer CLI fits

The Runlayer CLI (runlayer) is not a third way to connect. It is a helper program on the user’s machine. Users don’t need it to use Runlayer Plugin or a hosted connector’s endpoint: Claude, ChatGPT, Cursor and other clients connect with the MCP URL and a sign-in. Install the CLI when you need one of these:
  • Local MCPs. The client launches runlayer run <server-id>, and the CLI proxies to the MCP server on the user’s machine. See Local MCPs.
  • Auto Sync. runlayer setup sync writes auto-synced plugins (including Runlayer Plugin) and connectors into each local client’s config, so users don’t add them by hand. See Auto-Sync to Clients.
  • Skill sync to devices. The managed CLI package syncs skills into client skill folders every hour. See Sync to devices.
  • Native plugin install. For Claude Code, Codex, Cursor and VS Code, Add to Client offers runlayer plugins add, which installs Runlayer Plugin as a native plugin for that client. The same dialog also shows the plain MCP setup, which needs no CLI. When flat routing is on, Codex receives flattened connector tools only if the CLI set up its install.
Session and enforcement hooks don’t need the CLI on managed devices. The AI Watch package is a separate aiwatch binary that installs the hooks itself when Sessions or enforcement is on. runlayer setup hooks is the per-user alternative for a single macOS or Linux machine. To roll the CLI out to a fleet, deploy the signed CLI package (Apple Silicon macOS, Windows x64, Linux x86_64). It has no Python or uv prerequisite. The uvx runlayer ... commands in the app and in some guides run the same CLI through uv. On endpoints where security tools block uv, install the package and run the same command as runlayer ....

Authentication is the same for both

Regardless of which endpoint a client uses, the connection is authenticated — there is no anonymous access:
  • Interactive clients (Claude, ChatGPT, Cursor, …) authenticate the human user via OAuth/SSO. Runlayer challenges unauthenticated requests with a 401 before anything reaches the upstream server.
  • Agents and machine callers use an Agent Account token — either a machine-to-machine (M2M) token that acts as the agent itself, or an on-behalf-of (OBO) token minted via RFC 8693 token exchange so the agent acts with the intersection of agent + user permissions.
  • Scheduled jobs and automation tools on the unified endpoint authenticate as a user, with a personal API key or a stored OAuth session. Runlayer Plugin always needs a user, so it rejects organization API keys and M2M agent tokens. See Unattended automation and scheduled jobs.
For per-connector auth to upstream SaaS (OAuth 2.1, Bearer, OAuth Broker), see Connectors and the OAuth Broker. Connecting the client and authorizing individual connectors are separate steps. You don’t have to authorize connectors up front in the Runlayer app — users can add the endpoint first and authorize each connector afterwards. With Runlayer Plugin, ChatGPT, and Claude, the prompt arrives in the chat on the first tool call; clients pointed directly at a connector URL fetch its tool list when the connector is added, so they typically prompt at that point instead. See Authorizing at use time.

Finding the URL

  • Unified endpoint: open the Runlayer Plugin page and click Add to Organization. The MCP Server URL is shown in the dialog along with client-specific setup steps.
  • Individual connector: open the connector’s detail page and use its connect / client-setup dialog. Runlayer generates client-specific config (Cursor, VS Code, Claude, Codex, the TypeScript/Python SDKs, and more) with the correct URL pre-filled.

Remote dev environments and headless machines

A coding agent such as Claude Code can run on a machine the developer reaches over SSH or a web terminal: a Kubernetes pod per branch, a cloud dev box, a devcontainer. The setup is the same as on a laptop. The difference is that the developer’s browser is on another machine, so every sign-in step has to work without a local browser.
  1. Install the Runlayer CLI in the image. The .deb, .rpm and .tar.gz packages are x86_64 only. On arm64 or other architectures, use uv tool install runlayer (Python 3.10 or later). Install it at the same path in every environment, because the hooks call the CLI by its absolute path.
  2. Each developer signs in once: runlayer login --host https://<your-runlayer-host>. Login uses a device code: the CLI prints a URL and a code, and the developer approves on any device with their normal SSO. Nothing has to call back into the remote machine.
  3. Install the hooks after login: runlayer setup hooks --client claude_code --install --event-hooks --yes. They send the agent’s shell, file and MCP activity to Sessions and apply scanning and blocking. Add --mode monitor to observe without blocking. Hooks read the developer’s sign-in each time they fire, so they act as that developer.
  4. Connect the Runlayer Plugin at https://<your-runlayer-host>/mcp. Clients sign in to it with browser OAuth that redirects to localhost on the machine running the client, which a browser on the developer’s laptop can’t reach. On a remote machine, send a personal user API key in the x-runlayer-api-key header instead:
    The key acts as that developer, so their policies and connector grants apply as they would on a laptop. Organization API keys are rejected here. The key sits in the client’s config file, so give each developer their own key and keep it out of the image.
  5. Persist each developer’s home directory across environments, at least ~/.runlayer (CLI sign-in; without a system keyring the key is stored in ~/.runlayer/config.yaml), ~/.claude (hooks) and ~/.claude.json (Claude Code’s user-level MCP servers). If they aren’t persisted, the developer signs in again in every new environment.
Local connectors aren’t part of the Runlayer Plugin. Add them with runlayer run, and see OAuth on a headless host for connectors that sign in with their own OAuth.

Next steps

Runlayer Plugin

The unified MCP entrypoint — install paths and tool discovery.

Connectors

Add, configure, and connect individual MCP servers.

Agent Accounts

M2M and on-behalf-of (OBO) tokens for agents and frameworks.

Local MCPs

Connect MCP servers that run on the user’s machine.