> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runlayer MCP

> Use Runlayer's built-in self-MCP to answer audit log + analytics questions and manage your workspace.

Runlayer MCP (the **platform self-MCP**) is a first-party MCP server that lets an assistant ask questions about **Runlayer itself**: usage analytics, audit logs, server inventory, policies, plugins, and more.

It is the fastest way to answer "what happened?" and "how is adoption going?" without clicking around the UI.

**Runlayer MCP is not the same as [Runlayer Plugin](https://docs.runlayer.com/runlayer-plugin.md).** Installing Runlayer MCP does **not** expose your organization's connector MCPs — it only exposes the curated set of platform tools described below (audit logs, analytics, inventory, governance). Runlayer Plugin is the separate unified entrypoint for connector tools, and even there, connectors are exposed conditionally: only active hosted connectors the user can access through policy, never local, draft, disabled, or policy-blocked connectors.

> [!NOTE]
>
> All Runlayer MCP tool calls are governed by your Runlayer permissions and show up in&#x20;
> [Audit Logs](https://docs.runlayer.com/platform-audit-logs.md).

***

## 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_server` and `update_server` support 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)
* **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, and `confirm=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_agent` requires `ai_provider_id` and accepts optional `model` and `icon` parameters; `update_agent` covers metadata and settings such as `is_disabled`, and accepts `ai_provider_id` to move an agent to a different AI provider (pass it alongside `model` when the new model lives on a different provider).
  * Agent models: list available models for agents and update an agent's model
  * Agent icons: `create_agent` and `update_agent` accept a predefined icon, an emoji, or an uploaded icon. `generate_agent_icon` draws an AI icon suggestion, the same as **Generate** in the icon picker, and returns a key you pass to `update_agent` to apply it. Needs edit access to the agent
  * Agent ownership: `transfer_agent_owner` makes 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 and `confirm=true`. Agents can't call this tool
  * [Version history](https://docs.runlayer.com/platform-agents.md#version-history): `list_agent_versions` lists an agent's versions, newest first, with what changed and who made each change. `get_agent_version` returns the full configuration one version saved, with environment variable names but never their values. `restore_agent_version` saves 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. Pass `expected_current_version` to refuse with `conflict` if 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 and `confirm=true`
  * [Usage limits](https://docs.runlayer.com/platform-agents.md#usage-limits): `get_agent` returns the agent's spend and run caps with current usage and reset times. `update_agent` sets or removes the daily and weekly [cost budgets](https://docs.runlayer.com/platform-agents.md#cost-budgets); only agent managers can change limits
  * Schedules: `run_agent_schedule_now` runs 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 and `confirm=true`
  * Webhooks: `update_agent_webhook` renames a webhook. `create_agent_webhook` and `set_agent_webhook_signing` turn 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_attempts` lists a trigger's recent polls, `poll_agent_trigger_now` runs **Fetch now** (`confirm=true`), and `list_agent_trigger_target_options` lists the live choices for a trigger's target fields, such as Slack channels or GitHub repositories. Needs edit access to the agent
  * [Evals](https://docs.runlayer.com/platform-agent-evals.md): `delete_agent_eval` deletes an eval, `set_agent_eval_human_verdict` records your verdict on an eval case, and `suggest_agent_eval_runs` picks an eval's source runs from a plain-language description. `set_agent_run_annotation`, `delete_agent_run_annotation` and `list_agent_run_annotations` manage pass/fail labels on runs, and `analyze_agent_run_failures` groups failed runs by cause. All need edit access to the agent; the changes need `confirm=true`
  * [GitHub access](https://docs.runlayer.com/platform-agents-github.md): 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 optional `owner/repo` list (`grant_agent_github_access`), and revoke it (`revoke_agent_github_access`). All three need Manage org settings; the writes need `confirm=true` and 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](https://docs.runlayer.com/platform-artifacts.md): 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](https://docs.runlayer.com/artifacts/create.md) for the workflow.

> [!TIP]
>
> If you are unsure what to do next, ask your assistant to "use Runlayer MCP and tell me what
> tools you have available" and then pick the smallest set of tools needed for the task.

***

## 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).

> [!NOTE]
>
> Building an agent that calls Runlayer MCP programmatically? See&#x20;
> [Agent Accounts](https://docs.runlayer.com/platform-agent-accounts.md) 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](mailto: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=true` parameter. 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](https://docs.runlayer.com/platform-agent-accounts.md) 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 example `update_agent`. With an OBO token it can then change only the agents its delegating user can edit; any other agent-changing tool fails with `agent_account_not_granted`. A grant covers a whole tool, not individual changes: `update_agent` can also replace an agent's connectors and skills through its `connectors` and `skill_ids` parameters (it cannot transfer ownership), so grant the narrower tools, such as `add_agent_connectors` or `add_agent_skills`, when those are all the harness needs.

***

## Related resources

> [card] [Analytics](https://docs.runlayer.com/platform-analytics.md)
>
> UI analytics dashboard

> [card] [Audit Logs](https://docs.runlayer.com/platform-audit-logs.md)
>
> Activity history + investigations

> [card] [Incidents](https://docs.runlayer.com/platform-incidents.md)
>
> Grouped security inbox

> [card] [Sessions](https://docs.runlayer.com/platform-sessions.md)
>
> Session monitoring + enforcement

> [card] [Agent Accounts](https://docs.runlayer.com/platform-agent-accounts.md)
>
> Programmatic auth for agents

> [card] [MCP Troubleshooting](https://docs.runlayer.com/mcp-troubleshooting.md)
>
> Debug MCP connection + permission issues


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.