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_toolsto find the right tool, thenexecute_toolto 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.
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.
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 syncwrites 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.
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
401before 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.
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.-
Install the Runlayer CLI in the image. The
.deb,.rpmand.tar.gzpackages are x86_64 only. On arm64 or other architectures, useuv 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. -
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. -
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 monitorto observe without blocking. Hooks read the developer’s sign-in each time they fire, so they act as that developer. -
Connect the Runlayer Plugin at
https://<your-runlayer-host>/mcp. Clients sign in to it with browser OAuth that redirects tolocalhoston 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 thex-runlayer-api-keyheader 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. -
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.
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.