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

# MCP vs. CLI for Agents

> Why route agent tool access through MCP instead of giving agents raw CLI access, and how Runlayer governs both

## Why this comes up

A common question from teams evaluating agent tooling is: *"CLI-based agents feel
faster and simpler — why route everything through MCP?"*

The short answer: **speed and security are not the same axis.** A raw CLI gives an
agent broad, largely unscoped access to a machine, which is hard to observe and
hard to constrain. MCP gives you a typed, per-tool boundary that Runlayer can
authenticate, scope, scan, and audit. In practice most CLI agent frameworks also
speak MCP under the hood, so the "CLI vs. MCP" framing is usually a question of
*where the control point lives*, not whether MCP is involved at all.

<Note>
  Runlayer governs both surfaces. You do not have to choose: MCP traffic flows
  through the [Runlayer gateway](/runlayer-mcp), and CLI / IDE activity is
  captured through [client hooks and Sessions](/platform-sessions).
</Note>

## What raw CLI access means for an agent

Handing an agent a shell or an unrestricted CLI typically grants:

* The ability to run arbitrary commands, read and write any file the process can
  reach, and make outbound network calls.
* Access that is scoped to the *user or service account*, not to an individual
  capability. You cannot easily allow `read a ticket` while denying
  `delete a repository` — it is one blanket grant.
* Limited structured visibility. Command output is unstructured text, so
  detecting data exfiltration, secret leakage, or destructive actions requires
  parsing free-form shell history after the fact.

This is why unconstrained CLI access maps to several risks described in
[Security Threats](/security-threats) and the
[MCP Security Best Practices](/mcp-security-best-practices) checklist.

## Why MCP is easier to secure

MCP exposes tools as discrete, typed operations. That structure is what makes
governance possible:

| Control                   | Raw CLI                     | MCP through Runlayer                                                               |
| ------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
| Identity                  | Machine / user account      | Per-connector identity, OAuth broker, [agent accounts](/platform-agent-accounts)   |
| Authorization             | All-or-nothing shell access | Per-tool [policies](/platform-policies) and role scoping                           |
| Input / output inspection | Unstructured text           | [ToolGuard](/runlayer-toolguard) scans args and results (PII, credentials, intent) |
| Audit                     | Shell history, if enabled   | Structured [audit logs](/platform-audit-logs) per tool call                        |
| Runtime behavior          | Hard to model               | [AgentGuard](/agentguard) session-level trajectory monitoring                      |

Because each MCP tool call is a discrete event, Runlayer can allow, alert, mask,
or block at the granularity of a single operation instead of an entire session.

## "But the CLI feels faster"

Two things are usually behind the perceived speed difference:

1. **Most CLI agent runtimes already wrap MCP.** The CLI is a front end; the tool
   calls it issues are frequently MCP calls. Adding Runlayer as the control point
   does not change the interaction model — it adds policy, scanning, and audit to
   traffic that was already MCP.
2. **Local execution latency.** For genuinely local tools, Runlayer runs the CLI
   as a controlled local proxy rather than removing it. See
   [Local MCPs](/local-mcps): the AI client launches `runlayer run <server-id>`,
   which authenticates, checks policy, and forwards the request to the local MCP
   with minimal overhead.

So the tradeoff is not "fast CLI vs. slow MCP." It is "ungoverned access vs.
governed access," and Runlayer keeps the governed path fast.

## How Runlayer covers both surfaces

* **MCP servers** — proxied through the [Runlayer gateway](/runlayer-mcp) so every
  tool call is authenticated, policy-checked, scanned, and logged.
* **CLI and IDE agents** — captured through [client hooks](/platform-sessions),
  which record shell commands, file reads and writes, web fetches, and local tool
  activity alongside MCP calls. Hooks can also block unmanaged Shadow MCP sources.
* **Custom agent runtimes** — integrate the [Runlayer Hooks SDK](/runlayer-hooks-sdk)
  (TypeScript or Python) to send the same lifecycle and tool events through the
  hook pipeline.

The recommended path is MCP through the gateway for connectors, plus hooks for any
CLI/IDE surface you cannot proxy — so you get one consistent control and audit
plane regardless of how the agent invokes tools.

## Related

<CardGroup cols={2}>
  <Card title="MCP Security Best Practices" icon="shield-check" href="/mcp-security-best-practices">
    The full checklist for safely deploying MCP servers.
  </Card>

  <Card title="Security Threats" icon="triangle-exclamation" href="/security-threats">
    Threat model for agent tool access, including unrestricted execution.
  </Card>

  <Card title="Sessions" icon="timeline" href="/platform-sessions">
    Monitor CLI and IDE agent activity through client hooks.
  </Card>

  <Card title="Local MCPs" icon="terminal" href="/local-mcps">
    How the Runlayer CLI proxies local MCP servers with minimal overhead.
  </Card>
</CardGroup>