Policies - Runlayer

Managing Access Policies

After approving MCPs, you control who can access them through access rules. Runlayer’s policy system combines fine-grained permissions with ease of use, achieving both accuracy and least privilege by default.

How Access Rules Work

Access rules grant permissions to users, groups, roles, or agent accounts for specific MCP servers. Each rule can include multiple principals of the same type — for example, several users or several groups in one rule. Applies To (Who gets access):

User: One or more individual employees by email/ID
Group: One or more teams synced from your SSO (Engineering, Marketing, etc.)
Role: One or more job functions or custom roles
Agent Account: One or more machine-to-machine identities (see Agent Accounts)
Attributes: Match users or agent accounts by identity attributes (e.g., department, environment). User attributes sync from your IdP; agent account attributes are admin-managed. Attribute rules are subject-type-agnostic — assigning an attribute to an agent account makes it inherit every existing rule scoped to that attribute
Everyone: Wildcard principal that matches all subjects, including users and agent accounts (typically used in global deny policies)

Access Scope (What they can access):

Entire Server: Full access to all tools in the MCP
Specific Tools & Resources: Fine-grained selection of individual tools

Conditions (Advanced - Optional):

Add runtime rules based on tool arguments (e.g., restrict SQL queries to specific tables)
Enforce network restrictions (e.g., corporate IP ranges only)
Validate OAuth session properties (e.g., require verified accounts)
Block specific MCP clients

This design ensures you can easily grant appropriate access while maintaining security through least privilege.

Policy conditions evaluate runtime context — tool arguments (payload.*), request metadata like IP and client, OAuth session state, tool annotations, and session history (meta.session.*). They do not perform semantic analysis of what the user is trying to accomplish. For intent-level monitoring — detecting when an agent’s behavior diverges from the user’s intent across a session — see AgentGuard.

How Runlayer Enforces Least Privilege

Policies are one of several enforcement layers that work together. A request must pass all of them:

Platform roles (FGA) — control who can use platform features at all, like creating policies or managing connectors. See Roles & Permissions.
Access policies (PBAC) — server-level allow/deny rules and global deny rules, evaluated by the proxy on every tool invocation (this page).
Identity-scoped tokens — Agent Accounts authenticate with their own credentials; M2M tokens enforce agent-account policies, and OBO tokens enforce the intersection of the agent’s and the delegating user’s policies.
Runtime conditions — argument, network, OAuth, annotation, and session-history checks applied at invocation time.

Example — support agent using Slack: an admin’s Super Admin role lets them create the rule; a server-level rule grants the agent account access to only list_channels, read_messages, and search_messages on the Slack MCP; the agent’s OBO token limits it to what the delegating user is also allowed; and a global deny with meta.tool.annotations.destructiveHint EQUALS true backstops everything. See also Agents for scoping agent workloads.

Policy Types

Runlayer supports two types of permission policies, plus approval rules that layer on top of them:

Server-Level Policies

Manage access to specific MCP servers. Navigate to My connectors → [Server Name] → Policies tab.

Scope: One or more specific servers
Action: Allow or Deny
Use for: Granting access, fine-grained tool restrictions
Example: Allow Finance group to use database query tools

Global Policies

Organization-wide restrictions that apply everywhere. Navigate to Settings → Policies.

Scope: All servers, tools, and resources (*)
Action: Deny only
Use for: IP blocks, client restrictions, compliance requirements
Example: Block all access from outside corporate network

Use global policies for organization-wide security controls, and server-level policies for granting and managing access to specific resources.

Human approval rules

Human approval rules are in beta. Contact your Runlayer account team to enable them.

Approval rules are a separate kind of policy. They do not grant access — they add a human checkpoint on top of access a permission policy already granted. A caller still needs an allow policy to reach a tool; the approval rule decides whether a human has to sign off before the call runs.

Scope: All connectors, or specific ones
Action: Requires approval
Use for: Sensitive tools that should stay available but never run unattended
Example: Require approval before any tool annotated as destructive runs

Create them in Settings → Policies → Add approval rule, or per connector in My connectors → [Server Name] → Policies → Add approval rule. Conditions are optional: a rule for Everyone with no conditions requires approval for every tool call in its scope, which is the broadest form. Quick-start templates cover the common cases (destructive tools, external network access, untrusted MCP clients). Approval rules match on tool calls only. Unlike permission policies they cannot be narrowed to specific resources, because the approval prompt is raised from the tool-call path. For what happens once a rule matches — the run pausing and approvers being notified — see human-in-the-loop approvals.

Unified Policies

Connector rules are one instance of a broader model. A unified policy grants or denies named actions on a resource to a principal. The resource can be a connector, agent, skill, plugin, artifact, agent account, team, or the organization itself. Sharing an agent, giving a role an admin capability, and letting a group call a connector tool are all the same shape. Unified policies on non-connector resources become available as the unified policy engine rolls out to your workspace. Until then a unified body for one of those resources answers 409 with code unified_policy_engine_inactive for an admin with the security-policies capability, and for a resource owner or anyone holding share on the resource once your workspace’s policy data has been migrated to the unified store. Before that migration the owner door described below is closed and everyone but the admin gets 403. Connector-shaped bodies are unaffected.

Request shapes

POST /api/v1/policies accepts two body shapes. The connector shape is unchanged and keeps working. Both use the RUNLAYER_URL and API_KEY conventions from the agent account cookbook.

Connector shape
Unified shape

curl -s -X POST "$RUNLAYER_URL/api/v1/policies" \
  -H "x-runlayer-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "group", "ids": ["'$GROUP_ID'"] },
    "kind": "permission",
    "action": "allow",
    "scope": { "servers": ["'$SERVER_ID'"], "tools": "*", "resources": "*" },
    "description": "Support group can use the Slack connector",
    "conditions": []
  }' | jq '{id, principal, action}'

principal accepts user, group, role, agent, attributes, or any (shown as Everyone in the UI). action is allow or deny. scope names servers, tools, and resources (* for all).

curl -s -X POST "$RUNLAYER_URL/api/v1/policies" \
  -H "x-runlayer-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "group", "ids": ["'$GROUP_ID'"] },
    "kind": "permission",
    "effect": "allow",
    "resource": { "type": "agent", "ids": ["'$AGENT_ID'"] },
    "actions": ["view", "run"],
    "description": "Support group can run the triage agent",
    "conditions": []
  }' | jq '{id, principal, effect, resource, actions}'

kind is permission or approval_requirement. effect is allow or deny; omit it for approval requirements. resource is { "type": "<resource type>", "ids": ["<uuid>"] }, { "type": "<resource type>", "all": true }, or { "type": "org" } for organization-level actions. actions lists action names valid for that resource type. conditions takes the same rule groups as the connector shape; payload conditions only make sense with connector tool actions.

Resource types and actions

Every resource type except org, policy and agent_account carries the shared actions view, edit, share, manage_access, delete, and transfer_ownership. Each type adds its own. An agent account is not shareable and carries only view, use, edit, edit_security, edit_permissions, rotate_credentials and delete. Its use is reserved and grants or denies nothing yet. edit_security covers the account’s server scoping, DPoP, strict mode and login redirect URIs, token and delegation lifetimes, and re-enabling it, on top of edit (identity attributes need the agent account administrator capability, whatever the grants); rotate_credentials issues a new client secret. A grant of edit alone reaches neither. * matches every action on the type. Actions are flat, so granting manage_access does not imply view. The policy type is reserved.

Resource type	Additional actions
`connector`	`use`, `call_tool:` or `call_tool:<name>`, `read_resource:` or `read_resource:<uri>`, `edit_security`, `run_diagnostics`, `view_metrics`
`agent`	`run`, `view_runs_own`, `view_runs_all`
`skill`	`use`
`plugin`	`use`
`artifact`	`download`
`agent_account`	`view`, `use`, `edit`, `edit_security`, `edit_permissions`, `rotate_credentials`, `delete` (no shared actions)
`team`	`join`, `share_assets`
`org`	Admin capabilities, listed below. No shared actions.

The org actions are manage_admins, view_user_info, manage_org_settings, manage_mdm_config, view_audit_logs_own, view_audit_logs_all, view_unredacted_content, manage_audit_redaction, view_metrics_own, view_metrics_all, view_ai_outputs_all, export_usage_data, manage_security_policies, view_shadow_mcp, view_catalog, manage_catalog, access_deploy, use_management_api, manage_policies, create_connector, create_agent, create_skill, create_plugin, create_artifact, create_agent_account, create_team. The vocabulary also lists five synthetic org actions, use_assigned_connectors, use_teams, override_connector_access, use_procedures and manage_procedures. They mirror legacy role capabilities and grant nothing on their own.

Principals

Type	Selector	Body shape	Matches
`user`	`{ "type": "user", "ids": [...] }`	connector or unified	The listed users
`group`	`{ "type": "group", "ids": [...] }`	connector or unified	Members of the listed groups
`role`	`{ "type": "role", "ids": [...] }`	connector or unified	Users holding the listed roles
`agent`	`{ "type": "agent", "ids": [...] }`	connector or unified	The listed agent accounts
`attributes`	`{ "type": "attributes", "attributes": { "department": "Finance" } }`	connector or unified	Users and agent accounts whose attributes equal every listed value (exact equality, primitives only)
`any`	`{ "type": "any" }`	connector or unified	Any authenticated subject (Everyone in the UI)
`team`	`{ "type": "team", "ids": [...] }`	unified only	Members of the listed teams
`org`	`{ "type": "org" }`	unified only	Every member of the organization
`owner`	`{ "type": "owner" }`	unified only	Whoever owns the resource being checked. Used by the seeded owner templates; not something you normally write

These are the only spellings the API accepts, in either shape or in the unified shape alone as marked. agent_account, all: true and attrs are the engine’s internal forms and answer 422 on the wire, as does "ids": ["*"] for now. Responses echo the spellings above, except that a derived every-user or every-agent row reads back as "ids": ["*"].

Evaluation

Default deny. A subject holds an action on a resource only when a matching allow policy exists.
Any matching allow grants.
An explicit deny overrides every allow the engine evaluates, the owner’s and any share included. Checks that run before the engine are not subject to it. A role capability such as Manage security policies is read from the role itself, and a connector’s creator or a holder of the connector-management capability reaches the connector without a policy check. “Everyone except group X” is an org allow plus a group deny. A deny also beats public visibility, so a skill, plugin or agent shared with the whole organization stays closed to a denied subject.
Enforcement is live on every open, run, call and download. List pages do not yet subtract deny policies, so a public resource you have been denied can still appear in a list; opening it answers 403.

Presets

Viewer, Editor, and Manager are named preset bundles. They expand to raw actions and the engine only sees actions. The share dialog offers Viewer and Manager, its two permission levels; Editor is a policy builder and API bundle.

Preset	Actions
Viewer	`view` plus the consume action for the type (`use` and `call_tool:*` on connectors, `run` on agents, `download` on artifacts, `use` on skills and plugins). `team` has no consume action, so Viewer on a team is `view` only
Editor	Viewer plus `edit` and `share`
Manager	Editor plus `manage_access`

delete and transfer_ownership are never in a preset. Admins hold them. A resource’s owner holds every action on that resource. Connectors are the exception: the owner template grants view only, and connector access comes from connector policies.

Who can write policies

Admins with the security-policies capability write any policy.
The owner of a skill, plugin, agent, artifact or team, or anyone granted share on it, creates grants on exactly that resource. A grant is bounded by what its author holds, so the owner can grant any action on the resource and everyone else only the actions they hold. Connectors are the exception again. The owner template grants view alone, so connector access is granted through connector policies by admins with the security-policies capability, or by someone an admin has explicitly granted share on the connector, within what they hold. An agent account is not shareable, so only admins with the security-policies capability write unified policies on it.
Anyone granted manage_access on a resource edits or removes others’ grants on it.
An agent account’s connector policy (a connector-shape allow naming only agent accounts, on one connector, without conditions) can also be written by agent account administrators and, under the unified engine, by anyone holding edit_permissions on every account it names, the account’s owner included. Unless they administer the connector or created it, the tools are limited to the ones they can use themselves ("*" is saved as that list). Writing one for an account and connector that already have one updates that policy’s tools; a policy also covering other accounts or connectors answers 409. The same callers can change the tools of, or delete, a policy naming one of their accounts on one connector. See Agent accounts.

Two guardrails apply. System-seeded role and owner-template policies are read-only. A write that would leave the organization with no administrator able to manage policies is rejected.

Creating Access Rules

Navigate to MCP Policies

Go to the MCP you want to grant access to → Policies tab

Click 'New Access Rule'

Opens the access rule creation dialog

Select Who Gets Access

Choose a principal type (User, Group, Role, Agent Account, or Attributes), then select one or more from the dropdown. A single rule can include multiple principals of the same type.

Define Access Scope

Choose between:

Entire Server: Grant access to all tools (faster, simpler)
Specific Tools & Resources: Select individual tools (more secure, granular)

Add Rule

Click “Add Rule” to save - takes effect immediately

Access Rule Examples

Team-Wide Server Access

Scenario: Give engineering and devops teams access to the GitHub MCP

Applies To: Group "Engineering", Group "DevOps"
Access Scope: Entire Server
Result: All members of both groups can use every tool in the GitHub MCP

When to use:

Multiple teams need comprehensive access
Server tools are all appropriate for the groups
Simplicity is preferred over granularity

Fine-Grained Tool Access

Scenario: Give finance analysts read-only access to the Database MCP

Applies To: Group "Finance"
Access Scope: Specific Tools & Resources
Selected Tools:
  - list_tables
  - query_database
  - read_schema
Result: Finance can only query and read, not modify data

When to use:

Sensitive MCPs require least privilege
Only specific tools are needed
Different roles need different capabilities

This is how admins approve or deny individual tools inside an already-approved connector: connector approval decides whether the server is available at all, then server-level rules with Specific Tools scope (allow or deny) control each tool, enforced at invocation time and effective immediately. For a human checkpoint on specific tool calls during agent runs, see human-in-the-loop approvals.

Annotation-Based Access (Read-Only Tools)

Scenario: Give data analysts access to all tools, but only allow read-only ones at invocation time

Applies To: Group "Data Analysts"
Access Scope: Entire Server
Conditions:
  - meta.tool.annotations.readOnlyHint EQUALS true
Result: Data Analysts can see all tools, but can only invoke
        tools annotated as read-only

When to use:

Restrict access based on tool capabilities (read-only, destructive, etc.)
Enforce safety boundaries at invocation time
Works across any server with annotated tools

Individual User Access

Scenario: Give a contractor temporary access to specific Slack tools

Applies To: User "contractor@company.com"
Access Scope: Specific Tools & Resources
Selected Tools:
  - list_channels
  - read_messages
  - search_messages
Result: Contractor can read but not post or manage Slack

When to use:

Individual exceptions needed
Temporary access for specific users
Contractors or external collaborators
Testing new MCPs with a single user first

Conditional Access by Tool Arguments

Scenario: Allow finance team to query only sales and finance tables

Applies To: Group "Finance"
Access Scope: Specific Tools
Selected Tools: query_sql
Conditions:
  - payload.table BEGINS_WITH ["sales_", "finance_"]
Result: Finance can query sales_* and finance_* tables only

When to use:

Database access needs table-level restrictions
File systems need path-based access control
APIs need parameter validation
Sensitive data requires fine-grained control

Global Policy: Block External IPs

Scenario: Require all users to access MCPs from corporate network

Location: Settings → Policies (Global)
Applies To: Everyone
Action: Deny
Scope: All servers, tools, resources (*)
Conditions:
  - meta.request.ip NOT_IN_IP_RANGE ["10.0.0.0/8", "172.16.0.0/12"]
Result: Any access from outside corporate IPs is blocked

When to use:

Compliance requires network-based access control
Remote work must use VPN
Sensitive data needs IP restrictions
Organization-wide security policy

Restrict Gmail to Internal Recipients Only

Scenario: Prevent outgoing Gmail messages to external recipients, allowing only emails sent to your internal domain (e.g., @runlayer.com)

Location: MCP -> Connectors → Gmail → Policies tab
Applies To: Group "Everyone" (or specific teams)
Action: Deny
Access Scope: Specific Tools
Selected Tools:
  - send_email
  - send_draft
Conditions:
  - payload.to NOT_ENDS_WITH "@runlayer.com"
Result: Users can only send emails to @runlayer.com addresses;
        attempts to email external domains are blocked

You can extend this policy to also check payload.cc and payload.bcc fields using additional condition rules to ensure internal-only communication across all recipient types.

When to use:

Prevent data exfiltration via email in AI agent workflows
Enforce internal-only communication for sandbox or development environments
Provide guardrails for agents with Gmail access
Meet compliance requirements for regulated data
Test new AI workflows safely before allowing external communication

Block Tools That Accept Sensitive Parameters

Scenario: Prevent any tool that requires a password parameter from being invoked

Location: Settings → Policies (Global)
Applies To: Everyone
Action: Deny
Scope: All servers, tools, resources (*)
Conditions:
  - meta.tool.input_schema.required LIST_CONTAINS password
Result: Any tool whose JSON Schema lists "password" as a
        required field is blocked at invocation time

When to use:

Prevent credential-handling tools from running without approval
Block tools with dangerous parameter shapes (e.g., sql, command)
Works with any meta.tool.input_schema.* subfield (e.g., type, required)

input_schema is the tool’s JSON Schema object. Use dot-path subfields like meta.tool.input_schema.required with the list_contains operator, or meta.tool.input_schema.type with equals.

Block Destructive Tools Organization-Wide

Scenario: Prevent all users from invoking tools that may delete or overwrite data

Location: Settings → Policies (Global)
Applies To: Everyone
Action: Deny
Scope: All servers, tools, resources (*)
Conditions:
  - meta.tool.annotations.destructiveHint EQUALS true
Result: Any tool marked as destructive is blocked at invocation time

When to use:

Enforce safety boundaries across the organization
Protect production data from accidental deletion
Compliance requirements for data preservation
Gradual rollout (start with deny-all, grant exceptions)

Where annotations come from: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint are standard MCP tool annotations declared by the MCP server author in each tool’s definition. Runlayer reads them from the server’s tool listing and exposes them as meta.tool.annotations.* at invocation time. An annotation-based policy only matches tools whose server actually declares the annotation — for unannotated or untrusted servers, combine with name-based conditions (e.g., meta.tool.name REGEX "delete|remove|drop") or explicit Specific Tools scoping.

Dynamic Value References (`$meta.` / `$payload.`)

Condition values can reference runtime context dynamically by prefixing with $. This enables policies that compare one context field against another — for example, comparing a tool argument against values recorded earlier in the session. Supported prefixes:

$payload.<field> — Resolves to the current tool call’s argument value
$meta.<path> — Resolves to any meta.* context field

Behavior when a reference cannot be resolved:

If the referenced path doesn’t exist (e.g., the tool argument isn’t present), the rule fails (does not match) — even for negated operators like not_equals or list_not_contains. This prevents accidental allows when data is missing.

Example:

Condition rule:
  field: meta.session.payload_values_used.repo
  operator: list_not_contains
  value: $payload.repo

This rule matches when the current repo argument has not been used earlier in the session.

Session Payload Tracking

Runlayer can track which distinct tool argument values an agent uses during a session. Combined with deny policies and dynamic value references, this enables session isolation — once an agent accesses a resource (e.g., a specific repository), it cannot access different ones for the rest of the session. How it works:

A deny policy references $payload.<field> in its value — this tells Runlayer to track that field
On each allowed tool call, the argument’s value is recorded for the current session
On subsequent calls, meta.session.payload_values_used.<field> contains all previously-used distinct values
The deny policy evaluates against that list to block divergent values

Tracking is limited to the argument names your active policies reference, and records distinct values only (no counts or ordering).

Repository Isolation (Need-to-Know)

Scenario: Once an agent accesses a repository, block all other repositories for the rest of the session. Prevents context leakage across repos in shared agent sessions.

Location: MCP → [GitHub Server] → Policies tab
Applies To: Agent Account "Code Agent" (or Everyone)
Action: Deny
Access Scope: Entire Server
Conditions (all rules in one group — AND logic):
  - meta.session.payload_values_used.repo LIST_NOT_CONTAINS $payload.repo
  - meta.session.payload_values_used.repo LIST_REGEX ".+"
Result: After the first tool call with a "repo" argument, any call
        with a different "repo" value is denied

How the two rules work together:

Rule	Purpose
`list_not_contains $payload.repo`	Current repo is not in the set of previously-used repos
`list_regex ".+"`	At least one repo has been used before (prevents blocking the very first call)

Both rules must match (AND) for the deny to activate. On the first call, the second rule fails (no previous values), so the call is allowed and the repo is recorded. On subsequent calls with the same repo, the first rule fails (it IS in the list), so the deny doesn’t activate. On calls with a different repo, both rules match and the call is denied.

Edit the field name (repo) to match your MCP server’s argument name — common alternatives include repository, project, or owner/repo. The same pattern works for any field: database, account_id, workspace, etc.

Condition Field Reference

Every field you can use in a condition, with sample values. Fields marked invoke-only are evaluated at tool-invocation time and are not available during tool discovery (listing).

Tool Arguments (`payload.*`)

Field	Description	Example
`payload.<arg>`	Any argument of the tool being called, referenced by name. Dot paths reach into nested objects.	`payload.table` = `users`, `payload.path` = `/etc/passwd`

Server-scoped payload conditions cannot be used with connectors that have Skip Tool Input Validation enabled (global wildcard policies can still use them).

Request Context (`meta.request.*`)

Field	Description	Example
`meta.request.ip`	Client IP address	`203.0.113.42`
`meta.request.user_agent`	HTTP User-Agent header for client identification	`claude-code/1.2.0`
`meta.request.method`	HTTP request method	`POST`
`meta.request.path`	Request URL path	`/mcp/github`

Subject Attributes (`meta.subject.*`)

Field	Description	Example
`meta.subject.type`	Subject type (`user` or `agent`)	`user`
`meta.subject.id`	Subject UUID (user or agent ID)	`8f14e45f-ceea-467f-a7ce-16f5f8ab1c2d`
`meta.subject.email`	Email (users only, null for standalone agents)	`jane@acme.com`
`meta.subject.name`	Subject display name	`Jane Doe`
`meta.subject.roles`	Assigned roles	`Super Admin`
`meta.subject.groups`	Group memberships	`Engineering`
`meta.subject.organization_id`	Subject’s organization UUID	`1c9a7e6b-2d3f-4a5b-8c7d-9e0f1a2b3c4d`
`meta.subject.attributes`	Identity attributes — IdP-synced for users, admin-managed for agent accounts. For standalone agents this is the agent’s own attribute bag	`attributes.department` = `Finance`
`meta.user.*`	Deprecated alias for `meta.subject.*` (backward compatibility)	—

Acting Agent (`meta.actor.*`)

Set only when an Agent Account is making the call. For OBO (on-behalf-of) tokens, meta.subject.* stays the delegating user while meta.actor.* is the agent — so one rule can constrain both identities (e.g., require meta.actor.attributes.environment = production AND meta.subject.attributes.department = Finance). For non-agent subjects these fields are absent: positive operators (equals, contains, …) never match, but negative operators treat the absent value as satisfied — a deny with meta.actor.attributes.environment not_equals production fires for every plain-user call too. Pair negative meta.actor.* rules with meta.subject.type = agent to scope them to agent traffic.

Field	Description	Example
`meta.actor.id`	Agent account UUID	`8f14e45f-ceea-467f-a7ce-16f5f8ab1c2d`
`meta.actor.name`	Agent account display name	`Support Agent`
`meta.actor.organization_id`	Agent’s organization UUID	`1c9a7e6b-2d3f-4a5b-8c7d-9e0f1a2b3c4d`
`meta.actor.attributes`	Admin-managed identity attributes of the agent account	`attributes.environment` = `production`

Client Provenance (`meta.client.*`)

How the MCP client obtained its Runlayer credentials. Set only for connector OAuth clients; absent for dashboard sessions, API keys and agent-account tokens (same absent-value semantics as meta.actor.*).

Field	Description	Example
`meta.client.kind`	Proxy OAuth client kind: `dcr`, `cimd`, `pre_registered`, `manual`, `ema`, `agent`	`dcr`

The per-connector DCR / CIMD switches govern direct connections only. A self-registered client can still reach the connector through a plugin’s execute_tool. To apply the same restriction on every path, write a deny on the connector with meta.client.kind regex dcr|cimd. Pre-registered clients and agent accounts are unaffected.

Access Path (`meta.plugin.*`)

Whether the connector is reached directly or through an aggregate endpoint — a plugin (execute_tool), the Runlayer Plugin, or an agent account’s aggregate endpoint. Absent when the connector is called directly.

Field	Description	Example
`meta.plugin.id`	Aggregate (plugin or agent-account) UUID when accessed via one	`3f2b1c0d-9e8a-4b7c-a6d5-e4f3a2b1c0d9`

Intent	Rule
Self-registered clients blocked from a connector only via plugins	`meta.client.kind` `regex` `dcr	cimd`AND`meta.plugin.id regex .+`
Block connector via any plugin, for everyone	`meta.plugin.id` `regex` `.+`
Block connector via one plugin	`meta.plugin.id` `equals` `<plugin uuid>`
Allow direct access only	`meta.plugin.id` `not_regex` `.+`

Absent satisfies every negated operator, so a deny on meta.plugin.id not_equals <A> also fires for direct calls, and one on meta.client.kind not_equals pre_registered fires for dashboard and agent traffic too. Prefer positive regex matches, or AND with a regex .+ presence check.

Server Attributes (`meta.server.*`)

Field	Description	Example
`meta.server.id`	MCP server UUID	`5a2b8c1d-7e4f-4a6b-9c8d-0e1f2a3b4c5d`
`meta.server.name`	MCP server display name	`GitHub`
`meta.server.deployment_mode`	Server deployment mode	`hosted`
`meta.server.auth_type`	Authentication type	`oauth`
`meta.server.url`	Server URL	`https://api.githubcopilot.com/mcp/`

OAuth Context (`meta.oauth.*`)

Field	Description	Example
`meta.oauth.provider`	OAuth identity provider	`google`
`meta.oauth.scopes`	Granted OAuth scopes (list)	`repo`, `read:user`
`meta.oauth.token_expires_at`	OAuth token expiry timestamp	`2026-08-04T12:00:00Z`

Tool Context (`meta.tool.*`) — invoke-only

Field	Description	Example
`meta.tool.id`	Tool identifier	`send_email`
`meta.tool.name`	Tool name being invoked	`send_email`
`meta.tool.description`	Tool description from the MCP spec	contains `delete`
`meta.tool.annotations.readOnlyHint`	Tool is read-only (no side effects)	`true`
`meta.tool.annotations.destructiveHint`	Tool may delete or overwrite data	`true`
`meta.tool.annotations.idempotentHint`	Calling the tool multiple times has the same effect	`true`
`meta.tool.annotations.openWorldHint`	Tool interacts with systems outside the user’s account	`true`
`meta.tool.input_schema.<subfield>`	Tool input JSON schema (use subfields)	`meta.tool.input_schema.required` list_contains `password`

Session Context (`meta.session.*`) — invoke-only

Field	Description	Example
`meta.session.servers_used`	Server IDs accessed earlier in this session (list)	`$meta.server.id`
`meta.session.tools_used`	Tools called earlier in this session (list, format: `server_id:tool:tool_name`)	`$meta.server.id:tool:create_issue`
`meta.session.scopes_used`	Read/write scopes accessed earlier (list, format: `server_id:scope:read\|write`)	`$meta.server.id:scope:write`
`meta.session.payload_values_used.<arg>`	Distinct tool argument values used earlier in session (list, per argument name)	`$payload.repo`
`meta.session.session_id`	Canonical session identifier (UUID) for the current MCP session — the id Runlayer uses internally. Prefer this for session matching.	`3d7f9b2a-6c1e-4d8f-a5b9-7c0e2f4a6b8d`
`meta.session.external_session_id`	Raw client-supplied session id before normalization. Use only to match the exact value a client sent; otherwise prefer `meta.session.session_id`.	`claude_web:session-abc123`

Resource Context (`meta.resource.*`)

Field	Description	Example
`meta.resource.uri`	Resource URI	`file:///reports/q3.pdf`
`meta.resource.name`	Resource name	`q3.pdf`

Values starting with $ are dynamic value references: $meta.<path> and $payload.<field> resolve against the current call at evaluation time, so one rule can compare session history against whatever server or argument the call targets.

Common recipes:

Block access from outside the corporate network: meta.request.ip not_ip_range 10.0.0.0/8
Only allow read-only tools: meta.tool.annotations.readOnlyHint equals true
Restrict a connector to one Claude client: meta.request.user_agent contains claude
Deny tools that accept credentials: meta.tool.input_schema.required list_contains password
Pin an agent session to a single repo: see Repository Isolation

Available Operators

Conditions use operators in snake_case. All operators are listed below:

Category	Operator	Description
Equality	`equals`	Exact match
	`not_equals`	Does not match
String	`contains`	Value contains substring
	`not_contains`	Value does not contain substring
	`begins_with`	Value starts with prefix
	`not_begins_with`	Value does not start with prefix
	`ends_with`	Value ends with suffix
	`not_ends_with`	Value does not end with suffix
Regex	`regex`	Matches a regular expression (RE2 syntax)
	`not_regex`	Does not match a regular expression (RE2 syntax)
IP Range	`ip_range`	IP is within CIDR range(s)
	`not_ip_range`	IP is outside CIDR range(s)
List	`list_equals`	Deep equality between lists (order-sensitive)
	`list_not_equals`	Lists are not deeply equal
	`list_contains`	List contains value; if rule value is a list, all values must be present (subset check)
	`list_not_contains`	List does not contain value; if rule value is a list, none of its values can be present
	`list_regex`	List field entry matches regex
	`list_not_regex`	No list entry matches regex
	`list_any_not_regex`	At least one list entry does not match regex
	`list_ip_range`	List IP entry is within CIDR range(s)
	`list_not_ip_range`	No list IP entry is within CIDR range(s)

String operators (contains, begins_with, ends_with, and their negations) accept a single string or a list of strings. With a list, positive operators match if any pattern matches; negated operators match only if none do.

Negated operators (not_* and list_not_*) evaluate to true when the field is missing or unavailable, following the principle that an absent value cannot satisfy the positive condition.

The regex operators (regex, not_regex, list_regex, list_not_regex, list_any_not_regex) use RE2 syntax. RE2 is linear-time and immune to ReDoS, but does not support lookahead ((?=...)), lookbehind ((?<=...)), or backreferences (\1). Literal patterns with unsupported syntax are rejected at save time; a dynamic pattern (e.g. $payload.pattern) is only checked at evaluation time; if it can’t compile the condition is indeterminate, so a deny or approval rule built on it enforces restrictively and an allow rule does not grant — see Condition Value Matching. Existing policies that used lookahead patterns from the Quick Start templates continue to work during a transition period — they are automatically rewritten to equivalent RE2 patterns. If you have custom patterns with unsupported syntax, update them to use RE2-compatible alternatives (e.g., replace a negative lookahead deny with a list_any_not_regex complement).See Regular Expression Syntax for the full set of supported features and the differences from Python re (notably that \d, \w, \s are ASCII-only — use \p{Nd} / [\p{L}\p{N}_] for Unicode).

Condition Value Matching

When writing conditions, keep these matching rules in mind:

Behavior	Details
String comparisons are case-sensitive	`equals`, `contains`, `begins_with`, `ends_with`, and `regex` all match exact casing. `"Cursor"` does not match `"cursor"`.
Boolean values are case-insensitive	Fields like `meta.tool.annotations.readOnlyHint` or `meta.tool.annotations.destructiveHint` accept `true`, `True`, or `TRUE` interchangeably.
Numbers match their plain text form	`equals` and `not_equals` compare a numeric field with the value as text: a field of `5` matches `"5"`. Other spellings of the same number, such as `"5.0"` or `"1e4"` for `10000`, do not match.
Tool and resource names are case-sensitive	Scope entries (`tools`, `resources`) must match the exact name from the MCP server.
IP ranges use CIDR notation	`ip_range` / `not_ip_range` operators accept single or comma-separated CIDRs (e.g., `10.0.0.0/8, 172.16.0.0/12`).
Regex uses RE2 syntax	`regex`, `not_regex`, `list_regex`, `list_not_regex`, and `list_any_not_regex` use a linear-time engine (RE2). Character classes, anchors, quantifiers, alternation, `\b`, and named groups work; lookahead (`(?=…)`, `(?!…)`), lookbehind (`(?<=…)`, `(?<!…)`), and backreferences (`\1`) are not supported. A literal pattern using an unsupported construct is rejected when the policy is saved. A dynamic pattern (a reference like `$payload.pattern` resolved at evaluation time) can only be checked when it runs: if the resolved value fails to compile, the condition cannot be evaluated and is treated restrictively — a deny rule built on it blocks the request, an approval rule requires approval, and an allow rule does not grant. A server-side warning is logged. Prefer literal patterns, or validate dynamic sources upstream. Note also that `\d`, `\w`, `\s`, and `\b` are ASCII-only — use an explicit range or a Unicode property class (`\p{L}`, `\p{Nd}`) for non-ASCII text.

Best Practices

Start with Specific Tools, Not Entire Server

When in doubt, grant access to specific tools first. You can always expand later if needed.Why?

Easier to add permissions than remove them
Users won’t miss tools they didn’t know existed
Reduces attack surface if credentials are compromised

Use Groups, Not Individual Users

Create access rules for groups whenever possible, even if the group only has one member initially.Why?

Scales better as teams grow
Easier to audit (who’s in “Engineering” vs 50 individual rules)
Syncs automatically with SSO changes
Simplifies onboarding/offboarding

Leverage SCIM for Automatic Group Sync

Runlayer automatically syncs groups from your identity provider (IDP) via SCIM, mirroring your org structure.What this means:

Groups from Okta, Azure AD, or Google Workspace sync automatically
New employees added to groups get access immediately
Employees removed from groups lose access instantly
No manual group management needed

Best practice:

Create access rules using your existing IDP groups
Engineering, Sales, Finance groups work out of the box
Changes in your IDP reflect in Runlayer instantly

Regularly Audit Access

Review access rules quarterly:

Who has access to sensitive MCPs?
Are there users who no longer need access?
Can we tighten tool permissions?

Why?

Prevents scope creep
Maintains least privilege
Required for compliance

Use Conditions for Fine-Grained Control

Add conditions when scope alone isn’t enough:Good use cases:

Restrict database queries to specific tables
Limit file access to certain paths
Validate API parameters
Enforce network restrictions

Available context: tool arguments (payload.*), request metadata (meta.request.*), subject identity (meta.subject.*), server and OAuth attributes, tool annotations, and session history (meta.session.*). See the Condition Field Reference for every field with sample values.Start simple: Begin without conditions, add them only when needed for sensitive data or compliance.

Use Global Policies for Organization-Wide Rules

Apply security controls across all resources:Common use cases:

Block access from outside corporate network
Restrict access to approved clients only (e.g., allow only Cursor)
Require OAuth verification
Enforce compliance requirements

Remember:

Global policies can only DENY (not allow)
They apply to all servers, tools, and resources
Manage them in Settings → Policies
Test with small groups before applying to everyone

Combine with server policies: Use global denies for security, server-level allows for access grants.

Approvals

Review MCP requests

Security Best Practices

Security guidelines

Roles & Permissions

Admin capabilities behind org actions

Teams

Team ownership and sharing

​Managing Access Policies

​How Access Rules Work

​How Runlayer Enforces Least Privilege

​Policy Types

​Server-Level Policies

​Global Policies

​Human approval rules

​Unified Policies

​Request shapes

​Resource types and actions

​Principals

​Evaluation

​Presets

​Who can write policies

​Creating Access Rules

​Access Rule Examples

​Team-Wide Server Access

​Fine-Grained Tool Access

​Annotation-Based Access (Read-Only Tools)

​Individual User Access

​Conditional Access by Tool Arguments

​Global Policy: Block External IPs

​Restrict Gmail to Internal Recipients Only

​Block Tools That Accept Sensitive Parameters

​Block Destructive Tools Organization-Wide

​Dynamic Value References ($meta.* / $payload.*)

​Session Payload Tracking

​Repository Isolation (Need-to-Know)

​Condition Field Reference

​Tool Arguments (payload.*)

​Request Context (meta.request.*)

​Subject Attributes (meta.subject.*)

​Acting Agent (meta.actor.*)

​Client Provenance (meta.client.*)

​Access Path (meta.plugin.*)

​Server Attributes (meta.server.*)

​OAuth Context (meta.oauth.*)

​Tool Context (meta.tool.*) — invoke-only

​Session Context (meta.session.*) — invoke-only

​Resource Context (meta.resource.*)

​Available Operators

​Condition Value Matching

​Best Practices

​Related Resources

Approvals

Security Best Practices

Roles & Permissions

Teams

Managing Access Policies

How Access Rules Work

How Runlayer Enforces Least Privilege

Policy Types

Server-Level Policies

Global Policies

Human approval rules

Unified Policies

Request shapes

Resource types and actions

Principals

Evaluation

Presets

Who can write policies

Creating Access Rules

Access Rule Examples

Team-Wide Server Access

Fine-Grained Tool Access

Annotation-Based Access (Read-Only Tools)

Individual User Access

Conditional Access by Tool Arguments

Global Policy: Block External IPs

Restrict Gmail to Internal Recipients Only

Block Tools That Accept Sensitive Parameters

Block Destructive Tools Organization-Wide

Dynamic Value References (`$meta.` / `$payload.`)

Session Payload Tracking

Repository Isolation (Need-to-Know)

Condition Field Reference

Tool Arguments (`payload.*`)

Request Context (`meta.request.*`)

Subject Attributes (`meta.subject.*`)

Acting Agent (`meta.actor.*`)

Client Provenance (`meta.client.*`)

Access Path (`meta.plugin.*`)

Server Attributes (`meta.server.*`)

OAuth Context (`meta.oauth.*`)

Tool Context (`meta.tool.*`) — invoke-only

Session Context (`meta.session.*`) — invoke-only

Resource Context (`meta.resource.*`)

Available Operators

Condition Value Matching

Best Practices

Related Resources