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

Unified endpoint (Runlayer Plugin)Individual connector endpoint
What the client connects toOne MCP server that fronts every connector, skill, and platform tool the user can accessOne specific connector (e.g. Notion, Snowflake, an internal MCP)
URL shapehttps://<your-runlayer-host>/api/v1/proxy/plugins/<plugin-id>/mcp (human-friendly alias: /api/v1/proxy/runlayer/mcp)https://<your-runlayer-host>/api/v1/proxy/<server-id>/mcp
How tools are exposedTwo meta-tools — search_tools and execute_tool — so the model discovers tools on demand instead of loading every tool definitionThe connector’s tools are listed directly to the client
Setup surfaceOne entry per client, org-wideOne entry per connector, per client
Where you get itRunlayer Plugin page → Add to OrganizationConnector detail page → connect/client-setup dialog
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, and every execute_tool call runs 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 at scale. Instead of loading hundreds of raw tool definitions into context, the model calls search_tools to find the right tool, then execute_tool to run it. This keeps context small even with a large connector catalog.
  • 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 exactly one MCP server and you don’t want the meta-tool (search_tools/execute_tool) discovery layer — the client sees that connector’s tools directly.
  • 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. See Protecting MCP Servers.
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.

​
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.
For per-connector auth to upstream SaaS (OAuth 2.1, Bearer, OAuth Broker), see Connectors and the OAuth Broker.

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

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