All Runlayer MCP tool calls are governed by your Runlayer permissions and show up in
Audit Logs.
When to use Runlayer MCP
Use Runlayer MCP when you want to:- Pull analytics datasets for reporting (ex: top tools/users/servers over a date range)
- Query audit logs to investigate failures, policy denials, or suspicious activity
- Generate a server inventory (what MCPs exist, who can access them, what tools they expose)
- Inspect governance state (policies, access requests, security scanner settings)
- Create or maintain plugins, skills, and agents (admin / owner gated, confirm-required)
What it can do (high level)
Runlayer MCP intentionally exposes a curated set of high-leverage tools (not every backend endpoint). Common capabilities:- Audit logs
- Discover valid action and resource type filter values before listing or exporting audit logs
- List recent audit events with filters (action type, resource type/id, actor, correlation id, request id, client name)
- Fetch a single audit log entry with full details when you need deep inspection
- Bulk export audit logs as JSON or CSV — no 90-day hot-window restriction, up to 10 000 rows per call. Non-admins are scoped to their own logs; admins see org-wide logs. Sensitive-server details are redacted unless the caller has the viewer role
- Analytics exports (admin-only)
- Export dashboard datasets as CSV (same underlying metrics as the Analytics UI)
- Export per-server tool health + usage breakdowns as CSV
- Read the agent usage feed: every agent’s creator, consumers, sharing, and token usage (
get_agent_usage_report,list_agent_usage_consumers; needs View company metrics and Export usage data) - Read the Usage page’s Spend tab breakdowns with the same numbers the UI shows: spend per provider and model (
get_spend_cost_breakdown), the All users list (get_spend_people_usage), and spend by department (get_spend_department_usage). Each needs View company metrics and covers at most 31 days per call
- Servers
- List servers you can access
- Get server details + generate MCP client install links (Cursor / VS Code)
- List tools/resources/prompts for a server (via Runlayer proxy)
- Create, update, and delete servers (admin-only, confirm-required) —
create_serverandupdate_serversupport the same fields as the REST API, including OAuth configuration (manual and broker), audit log sensitivity, tool output offloading, MCP fingerprint, and deployment association
- Governance (mostly admin-only)
- List, read, create, update, and delete policies (full CRUD — mutations require explicit
confirm=true) - List access requests
- Read/update security scanner settings (mutations require explicit confirm)
- List, read, create, update, and delete policies (full CRUD — mutations require explicit
- Incidents
- List incidents with filters (status, priority, source type, date range) and pagination
- Get full incident details including grouped entries, available triage/remediation actions, and activity history
- Triage incidents (resolve, snooze, dismiss) and dispatch remediation actions (block tool, disable connector, escalate scanner) — mutations require explicit
confirm=true
- Sessions
- List recent sessions with filters (status, client, user, date range) and pagination
- Get session details including events, tool calls, scan results, and AgentGuard findings
- Stop a session so its tool calls are denied, and clear the stop (
stop_session,clear_session_stop). Stopping also cancels the session’s running Runlayer Agents runs, whoever started them. Both need Manage security policies, a reason, andconfirm=true, and both are recorded in the audit log. Only a session Runlayer has recorded can be stopped; an unknown session id is refused
- Automation building blocks
- Plugins: create/update, manage connectors (tool allowlists) + attach skills
- Skills: create/update skill instruction files used by plugins
- Agents: manage agents; edit connectors and skills incrementally (
set_agent_connectors/add_agent_connectors/remove_agent_connectors,set_agent_skills/add_agent_skills/remove_agent_skills); create schedules/webhooks; configure Slack DM mode; enable/disable memory; enable/disable agents; delete agents (delete_agent, owner or agent manager only, confirm-required).create_agentrequiresai_provider_idand accepts optionalmodelandiconparameters;update_agentcovers metadata and settings such asis_disabled, and acceptsai_provider_idto move an agent to a different AI provider (pass it alongsidemodelwhen the new model lives on a different provider). - Agent models: list available models for agents and update an agent’s model
- Agent icons:
create_agentandupdate_agentaccept a predefined icon, an emoji, or an uploaded icon.generate_agent_icondraws an AI icon suggestion, the same as Generate in the icon picker, and returns a key you pass toupdate_agentto apply it. Needs edit access to the agent - Agent ownership:
transfer_agent_ownermakes another person in the organization the owner of an agent, with the same checks and warnings as Transfer owner in the Share dialog. Needs permission to transfer ownership andconfirm=true. Agents can’t call this tool - Version history:
list_agent_versionslists an agent’s versions, newest first, with what changed and who made each change.get_agent_versionreturns the full configuration one version saved, with environment variable names but never their values.restore_agent_versionsaves an earlier version as a new version, so the restore can be undone. It never changes environment variables or secrets, sharing, schedules or webhooks, and it returns connectors or skills deleted since that version as warnings. Passexpected_current_versionto refuse withconflictif someone saved a newer version in the meantime. All three need Use Agents; listing and reading need view access to the agent, and restoring needs edit access andconfirm=true - Usage limits:
get_agentreturns the agent’s spend and run caps with current usage and reset times.update_agentsets or removes the daily and weekly cost budgets; only agent managers can change limits - Schedules:
run_agent_schedule_nowruns a saved schedule once, now, like the schedule card’s Run now. It uses the schedule’s prompt and model with your connections and memory, shows under the schedule, and doesn’t move the schedule’s next or last run. Needs run access to the agent andconfirm=true - Webhooks:
update_agent_webhookrenames a webhook.create_agent_webhookandset_agent_webhook_signingturn request signing on, rotate the signing secret, or turn signing off; a new signing secret appears in the tool response only once. An agent can’t turn on signing for its own webhooks - Poll triggers:
list_agent_trigger_poll_attemptslists a trigger’s recent polls,poll_agent_trigger_nowruns Fetch now (confirm=true), andlist_agent_trigger_target_optionslists the live choices for a trigger’s target fields, such as Slack channels or GitHub repositories. Needs edit access to the agent; only the owner of the trigger’s connected account can run Fetch now, see what a poll returned, or change what the trigger watches and who receives its runs - Evals:
delete_agent_evaldeletes an eval,set_agent_eval_human_verdictrecords your verdict on an eval case, andsuggest_agent_eval_runspicks an eval’s source runs from a plain-language description.set_agent_run_annotation,delete_agent_run_annotationandlist_agent_run_annotationsmanage pass/fail labels on runs, andanalyze_agent_run_failuresgroups failed runs by cause. All need edit access to the agent; the changes needconfirm=true - GitHub access: read an agent’s GitHub access and the org’s GitHub App connections (
get_agent_github_access), grant a connection to an agent with an optionalowner/repolist (grant_agent_github_access), and revoke it (revoke_agent_github_access). All three need Manage org settings; the writes needconfirm=trueand are recorded in the audit log. Agents can’t call the grant or revoke tool. Connecting the GitHub App itself is only in Settings → Integrations, because it takes the App’s private key - Subagents: add, update, and delete subagents on an agent (confirm-required)
- Artifacts: create standalone files from text or base64 content, find and read accessible artifacts, update or edit standalone artifacts you own, and delete artifacts you can manage. Mutations require
confirm=true. See Create and update for the workflow.
Getting started
1
Make sure the Runlayer server exists (admin)
Go to Connectors, find Runlayer, and click Add connector if it is not already enabled.
If it is already installed, you should see a connector named Runlayer in the connectors UI.
2
Connect it to your AI client
In the Runlayer UI, open the Runlayer connector and click Add to Client (or copy
the proxy URL). Then enable/select the connector in your AI client.
3
Ask a reporting question
Start with one of the example prompts below. If you need a CSV export, ask for a CSV and a
short summary (the assistant can parse the CSV output).
Building an agent that calls Runlayer MCP programmatically? See
Agent Accounts for OAuth client credentials + token flows.
Example prompts (copy/paste)
Analytics (adoption + usage)
- “Use Runlayer MCP to export top tools used in the last 30 days as CSV, then summarize the top 10 and call out failure rate.”
- “Export tool calls hourly for the last 7 days (UTC) and describe the daily pattern.”
- “Which MCP clients (Cursor/Claude/etc) generated the most MCP activity last month? Export CSV and rank them.”
Audit logs (investigations)
- “Use Runlayer MCP to list recent tool_call_failure audit logs. Group by server name and show the most common error messages.”
- “Find audit logs with
correlation_id=<id>and summarize the sequence of events.” - “For the most recent policy denied events, show actor + server + tool and the violation reason.”
- “Export the last 30 days of security violation audit logs as CSV and identify the top offending tools.”
Incidents + sessions
- “Use Runlayer MCP to list open incidents from the last 7 days and summarize by source type.”
- “Get the details of the highest-priority incident and show the available remediation actions.”
- “List sessions for user@company.com from the last 24 hours and flag any with security violations.”
Inventory + debugging
- “List servers I can access, then for the Slack server list its tools and give me the install link for Cursor.”
- “I think a connector is missing tools. List the server tools via Runlayer MCP and compare to what the UI shows.”
Notes and gotchas
- Admin-only vs non-admin: some reporting and governance tools require admin access. Non-admins may see a reduced view (for example, audit logs are limited to the caller unless you are an admin).
- Safe-by-default mutations: tools that change state require an explicit
confirm=trueparameter. If your assistant asks to “confirm”, that is expected. - Large outputs: some audit log entries can be huge. Listing tools may omit large fields; fetch the specific record when you need the full payload.
- Changing agents from an agent: when Runlayer MCP runs inside a Runlayer agent’s own run (for example in Slack or the playground), that run can change only its own agent; changes to other agents fail with
agent_scope_denied. Attach Runlayer MCP to the agent as a connector to let it manage other agents with the permissions of the user it acts for. Your own harness on an Agent Account gets no agent-changing tools by default, even though everyone can use Runlayer MCP: an admin must connect its agent account to the Runlayer connector with the specific tools, for exampleupdate_agent. With an OBO token it can then change only the agents its delegating user can edit; any other agent-changing tool fails withagent_account_not_granted. A grant covers a whole tool, not individual changes:update_agentcan also replace an agent’s connectors and skills through itsconnectorsandskill_idsparameters (it cannot transfer ownership), so grant the narrower tools, such asadd_agent_connectorsoradd_agent_skills, when those are all the harness needs.
Related resources
Analytics
UI analytics dashboard
Audit Logs
Activity history + investigations
Incidents
Grouped security inbox
Sessions
Session monitoring + enforcement
Agent Accounts
Programmatic auth for agents
MCP Troubleshooting
Debug MCP connection + permission issues