# Use Maru from your agent

> The agent skill, the CLI, the local MCP server and the hosted MCP connector: what each one is for, which you need, the install commands and how they work together.

Canonical: https://maruaudio.com/docs/agent-setup
Documentation index: https://maruaudio.com/llms.txt

Maru works with the agent you already use. Four pieces connect it, and you
install only the ones your work needs. The CLI and both MCP servers run the
same operations under one permission model, so a project or a build looks the
same from Claude Code, Codex, Cursor, Claude, ChatGPT or a script.

## The four pieces

| Piece | What it is | Use it for |
| --- | --- | --- |
| Agent skill (`maru-agent`) | Instructions for a coding agent | Teaching the agent the Maru workflow and to ask the CLI for commands, schemas and guides |
| CLI (`maru`) | The `maruaudio` npm package | Creating, building and checking projects on your computer; signed in, your hosted projects, builds and generation |
| Local MCP server (`maru-local`) | `maru mcp` on stdio | The CLI's operations as MCP tools, on the project in your checkout |
| Hosted MCP connector (`maru`) | `https://maruaudio.com/mcp` | Your Maru account from any MCP client: projects and their source, guides, community modules, builds, new projects and sound generation |

The skill contains no tools. It tells a coding agent to check the machine with
`maru doctor`, read the guides for the task with `maru guide`, and look up exact
input schemas with `maru tools describe` before it acts. The CLI and the two
MCP servers do the work.

## Which do I need

| Your situation | Install |
| --- | --- |
| Building a plugin, kit or bank on your computer with Claude Code, Codex, Cursor or another coding agent | The skill and the CLI. Add the local server if you want the agent to call operations as MCP tools rather than shell commands. |
| Working on your Maru account from Claude, ChatGPT or Claude Desktop | The hosted connector. Paste the URL in the app's connector settings. |
| A coding agent that works on your account and your checkout | The skill, plus both MCP servers. |
| Scripts and CI | The CLI with `--json`, or the hosted API with a personal token. |

## Install

The skill needs no sign-in:

```bash
npx maruaudio skill install
```

Register the MCP servers with your coding agents:

```bash
npx maruaudio mcp install            # the hosted connector (maru)
npx maruaudio mcp install --local    # the local server (maru-local)
npx maruaudio mcp install --both     # both
```

Both commands work on the agents used in the current project. Add `--global`
to install for your user instead. `npx maruaudio` runs any command without a
global install; to keep `maru` on your path, run `npm i -g maruaudio`.

`mcp install` writes each agent's own configuration and keeps the other
servers there:

| Agent (`--client`) | This project | `--global` |
| --- | --- | --- |
| Claude Code (`claude-code`) | `.mcp.json` | runs `claude mcp add --scope user` |
| Cursor (`cursor`) | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
| VS Code (`vscode`) | `.vscode/mcp.json` | runs `code --add-mcp` |
| Codex (`codex`) | `~/.codex/config.toml` | `~/.codex/config.toml` |
| Gemini CLI (`gemini`) | `.gemini/settings.json` | `~/.gemini/settings.json` |
| Claude Desktop (`claude-desktop`) | `claude_desktop_config.json` for the local server; prints the Settings → Connectors steps for the connector | the same |

Without `--client`, it configures the agents it finds: those with files in
this project (or in your home folder with `--global`), Codex and Claude
Desktop where they are installed, and Claude Code when it finds none. Name agents with `--client`, which you can repeat.
`--dry-run` shows what would change without writing. A configuration file
that is not plain JSON is refused rather than overwritten; add the entry by
hand from [Connect your agent](https://maruaudio.com/docs/mcp-connect.md).

```bash
npx maruaudio mcp install --client cursor --both
npx maruaudio mcp status    # which agents have Maru configured, and where
npx maruaudio mcp remove    # takes the same options as install
```

Restart the agent, or reload its MCP servers, afterwards. The hosted connector
asks you to sign in to Maru in your browser the first time the agent uses it;
in Claude Code, run `/mcp`, select **maru** and choose **Authenticate**.

Claude, ChatGPT and other apps that take a connector URL in their settings are
set up by hand: [Connect your agent](https://maruaudio.com/docs/mcp-connect.md) has the steps for each.

## How the pieces work together

- **One set of operations.** Every Maru operation is a CLI command, an MCP tool
  and a typed call in the `maruaudio` library, with one input schema. The local
  server serves the same operations as the CLI, on the project in your
  checkout; `maru tools list` prints them.
- **One hosted catalog.** The hosted connector, the hosted API
  (`POST https://maruaudio.com/api/v1/ops/<name>`) and a signed-in `maru` run
  the same hosted operations, such as `maru project list`, `maru build list`
  and `maru audio generate`. [`/mcp/tools.json`](https://maruaudio.com/mcp/tools.json) publishes the
  list, and [Tools](https://maruaudio.com/docs/mcp-tools.md) explains each one.
- **One permission model.** Each hosted operation reads, creates, or spends
  generation credits, and each of those needs its own permission. A connector
  asks for `mcp:read` and `mcp:write` when you approve it and for
  `mcp:generate` the first time it generates. [`maru login`](https://maruaudio.com/docs/authentication.md)
  grants reading and creating by default; generation asks for
  `inference:run` separately (`maru login --scope` names the full set).
- **The skill ties them together.** It sends the agent to the CLI for
  discovery, so the agent sees the features of the version you installed. It
  also tells the agent to ask you before signing in, running paid or hosted
  generation, publishing, or confirming a destructive command.

A typical local session uses all four: the skill guides the agent, the hosted
connector finds your project and the guide, and the CLI or the local server
edits, builds and checks the checkout.

## Next

- [Agent skill](https://maruaudio.com/docs/skills.md): what the skill does and prompts to try.
- [Agents and MCP](https://maruaudio.com/docs/agents-and-mcp.md): the local server, guides and
  operation schemas in detail.
- [MCP overview](https://maruaudio.com/docs/mcp.md), [Connect your agent](https://maruaudio.com/docs/mcp-connect.md),
  [Workflows](https://maruaudio.com/docs/mcp-workflows.md) and [Tools](https://maruaudio.com/docs/mcp-tools.md): the hosted
  connector.