# Agents and MCP

> Install the Maru agent skill, serve Maru's operations over MCP, and let an agent discover guides and schemas from the CLI.

Canonical: https://maruaudio.com/docs/agents-and-mcp
Documentation index: https://maruaudio.com/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`. Three commands
connect an agent to it.

## 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://maruaudio.com/docs/skill.md) explains what the skill does and how to use it.

## MCP

```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://maruaudio.com/docs/authentication.md).

Register it with Claude Code once and it is available in every session:

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

For another MCP client, add the server to its configuration:

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

Without a global install, use `npx` as the command and `["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://maruaudio.com/docs/working-with-coding-agents.md) describes the
collaboration loop.