# Agents and MCP

> Install the Maru agent skill, register Maru's MCP servers with your coding agents, serve the local operations over MCP, and let an agent discover guides and schemas from the CLI.

Canonical: https://maru.audio/docs/agents-and-mcp
Documentation index: https://maru.audio/llms.txt

A coding agent uses Maru through the same CLI you do. Everything it needs to
know comes from the installed version: commands from `--help`, input schemas
from `maru tools describe`, and task guidance from `maru guide`. This page
covers each piece in detail; [Use Maru from your agent](https://maru.audio/docs/agent-setup.md)
explains which ones you need and how they fit together.

## The agent skill

```bash
npx maruaudio skill install
```

This installs the `maru-agent` skill for the coding agents in the current
project, using the open Skills CLI; it needs no sign-in. Add `--global` to
install it for your user instead, or `--agent <name>` to choose an agent.
`--dry-run` prints the Skills CLI command without running it. Without a
terminal, the command answers the Skills CLI's prompts itself. You can also run
the Skills CLI directly:

```bash
npx skills add maru-audio/maru-skill --skill maru-agent
```

Manage the installed skill with the same command:

```bash
npx maruaudio skill status   # installed? where, and for which agents
npx maruaudio skill update   # fetch the latest version
npx maruaudio skill remove   # uninstall (asks first; --yes to skip)
```

`maru doctor` also reports whether the skill is installed.
[Agent skill](https://maru.audio/docs/skills.md) explains what the skill does and how to use it.

The skill teaches the agent to use the CLI. To give the same agents Maru's MCP
servers as well, run `npx maruaudio mcp install`, described below.

## Remote MCP connector

Connect Claude, ChatGPT, Cursor, VS Code or any MCP client to your Maru account
with one URL:

```text
https://maruaudio.com/mcp
```

The client registers itself, opens Maru in your browser to sign in, and asks
you to approve its access; you never paste a password or key. The connector
reads the Maru guides, lists your Studio projects and reads their source,
searches published community modules and their open source, reports your
plug-in builds, lists the Studio templates, and creates Studio projects and
sound banks. Generating audio spends credits and needs a separate permission.
It cannot edit source or publish. Disconnect it in Settings → Access tokens.

For coding agents, one command adds it as `maru`:

```bash
npx maruaudio mcp install
```

This configures Claude Code, Cursor, VS Code, Codex, Gemini CLI or Claude
Desktop; [Use Maru from your agent](https://maru.audio/docs/agent-setup.md#install) lists where
each one's entry goes.

[MCP overview](https://maru.audio/docs/mcp.md) explains the remote server;
[Connect your agent](https://maru.audio/docs/mcp-connect.md) has the setup for each client,
[Workflows](https://maru.audio/docs/mcp-workflows.md) has prompts to try, and
[Tools](https://maru.audio/docs/mcp-tools.md) lists every tool.

## Local MCP server

```bash
maru mcp
```

`maru mcp` runs a Model Context Protocol server on stdio. It serves the same
operations as the CLI, with the same input schemas, so any MCP client can call
them. Operations that change files, such as builds, exports and source edits,
carry write annotations, so a client that honors read-only hints asks before
running them. Hosted operations use the credentials from
[`maru login`](https://maru.audio/docs/authentication.md).

Register it with your coding agents as `maru-local`, next to the hosted
connector:

```bash
npx maruaudio mcp install --local   # the local server only
npx maruaudio mcp install --both    # the local server and the connector
```

The entry runs `npx -y maruaudio mcp`, so it works without a global install.
To add it by hand, register it with Claude Code:

```bash
claude mcp add maru-local -- maru mcp
```

or add it to another MCP client's configuration:

```json
{
  "mcpServers": {
    "maru-local": {
      "command": "maru",
      "args": ["mcp"]
    }
  }
}
```

Without a global install, use `npx` as the command and
`["-y", "maruaudio", "mcp"]` as its arguments. The server works on the project
in the client's workspace roots, or the directory it was started in.

## Guides

```bash
maru guide list              # guides, each with the situation it applies to
maru guide read <name...>    # read one or more guides
```

Guides are short, versioned instructions for specific tasks: authoring a Graph
or a Processor, parameters and presets, faces with the UI kit, MIDI modules,
resources and builds. They match the version of Maru you installed, so an
agent should read them instead of relying on what it remembers.

## Operations and schemas

```bash
maru tools list                     # every operation
maru tools describe --json          # their JSON input schemas
maru tools call <operation> --input '{"key":"value"}'
```

Every Maru operation is a CLI command, an MCP tool and a typed call in the
`maruaudio` library at once. `maru tools describe` prints the schemas an MCP
client sees. `maru tools call` runs an operation by its registry name with JSON
input, which suits scripts that already build JSON. Each command also accepts
its operation name as an alias, for example `maru module_build` for
`maru module build`.

## A first prompt

```text
Use the maru-agent skill. Run maru doctor, then read the guides that match
this task. Make the delay repeats darker as they fade, using the existing DSP
leaves. Check the result with maru module check and maru module eval, and
summarize the changed files and what you verified.
```

[Working with coding agents](https://maru.audio/docs/working-with-coding-agents.md) describes the
collaboration loop.