# MCP: connect your agent

> Add the Maru MCP server to Claude, ChatGPT, Claude Code, Codex, Cursor or VS Code: one command for coding agents, setup steps for each client, what you approve, personal tokens, testing, disconnecting and troubleshooting.

Canonical: https://maruaudio.com/docs/mcp-connect
Documentation index: https://maruaudio.com/llms.txt

Connecting takes a minute: add one URL to your agent, sign in to Maru in your
browser, and approve what the agent may do. You never paste a password, key or
token. [MCP overview](https://maruaudio.com/docs/mcp.md) explains what the server does;
[Workflows](https://maruaudio.com/docs/mcp-workflows.md) has prompts to try once you are connected.

## Before you start

- **A Maru account.** Sign in at [maruaudio.com](https://maruaudio.com/login) once, with Google or
  GitHub, so the approval page knows who you are.
- **Set it up on a computer.** Add the connector in a desktop browser or a
  desktop app. In Claude and ChatGPT a connector added on a computer then
  appears in their phone apps on its own; the phone apps cannot add one.
- **Copy the URL, do not type it.** It must end in `/mcp`. Without that part
  most clients spin for a while and give up without an error.

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

## Coding agents: one command

For Claude Code, Cursor, VS Code, Codex and Gemini CLI, the Maru CLI adds the
server for you:

```bash
npx maruaudio mcp install
```

It writes the entry, named `maru`, into the configuration of each agent it
finds for the current project; add `--global` for your user, or
`--client <name>` to choose agents. Restart the agent, then sign in when it
first uses Maru (in Claude Code, run `/mcp` and choose **Authenticate**). For
Claude Desktop it prints the connector steps below. `--both` also adds the
local server for the project in your checkout.
[Use Maru from your agent](https://maruaudio.com/docs/agent-setup.md#install) lists every option and
file.

Pair it with the agent skill, which teaches a coding agent the Maru workflow
and the CLI:

```bash
npx maruaudio skill install
```

[Agent skill](https://maruaudio.com/docs/skills.md) explains what it does.

## Set up your client

Every client follows the same three steps: add the URL, sign in to Maru in the
browser window it opens, and approve. Leave any "client ID", "client secret"
or "API key" fields empty: the client registers itself. For a coding agent you
can skip the configuration step with
[`npx maruaudio mcp install`](#coding-agents-one-command).

### Claude (claude.ai and Claude Desktop)

1. Open **Settings → Connectors**.
2. Choose **Add custom connector** at the bottom of the list. On a Team or
   Enterprise plan an Owner adds it once under the organization's connectors,
   and each member then chooses **Connect**.
3. Name it `Maru` and paste `https://maruaudio.com/mcp` as the URL. Leave the
   advanced settings empty.
4. Choose **Add**, then **Connect**. A Maru page opens: sign in if asked, check
   the access, and choose **Approve**.
5. In a chat, open the tools menu and make sure **Maru** is on.

The free Claude plan allows one custom connector at a time.

### Claude Code

Add the server once:

```bash
claude mcp add --transport http maru https://maruaudio.com/mcp
```

Then run `/mcp` inside Claude Code, select **maru** and choose
**Authenticate**. Approve in the browser window that opens. Add `--scope user`
to the first command to make Maru available in every project.

### ChatGPT

Custom connectors use ChatGPT's developer mode, on the web, on plans that offer
it.

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on
   **Developer mode**.
2. Back in **Apps & Connectors**, choose **Create**.
3. Name it `Maru`, paste `https://maruaudio.com/mcp` as the MCP server URL and
   choose **OAuth** as the authentication. Leave the client ID and secret
   empty.
4. Confirm that you trust the connector, then approve on the Maru page.
5. In a conversation, add Maru from the **+** menu under developer mode.

Connectors work in written conversations, not in voice mode.

### Codex

```bash
codex mcp add maru --url https://maruaudio.com/mcp
codex mcp login maru
```

`codex mcp login` opens the browser to approve. `codex mcp list` shows whether
you are signed in.

### Cursor

Add Maru to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json`
in one project:

```json
{
  "mcpServers": {
    "maru": {
      "url": "https://maruaudio.com/mcp"
    }
  }
}
```

Open **Cursor Settings → MCP**, find **maru** and choose **Connect** (or
**Needs login**). Approve in the browser.

### VS Code

Add Maru to `.vscode/mcp.json` in your workspace, or run **MCP: Add Server**
from the command palette and choose HTTP:

```json
{
  "servers": {
    "maru": {
      "type": "http",
      "url": "https://maruaudio.com/mcp"
    }
  }
}
```

Start the server from the code lens above the entry. VS Code asks to sign in;
allow it and approve in the browser. Use the tools in Copilot Chat's agent
mode.

### Other MCP clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth
works the same way: give it the URL and it discovers sign-in from
`https://maruaudio.com/.well-known/oauth-protected-resource`. For a client
without browser sign-in, see [Use a personal token](#use-a-personal-token).

## What you approve

When your agent connects, Maru shows an approval page with:

- the name the agent registered under, for example "Claude";
- where approving sends you back, for example `claude.ai`. The name is chosen
  by the agent, so check this destination and only approve if you just added
  Maru there;
- the access it asks for:

| Permission | What it allows |
| --- | --- |
| `mcp:read` | Read Maru guides, templates, and your Studio projects and their source from your AI agent |
| `mcp:write` | Create Studio projects and sound banks in your account from your AI agent |
| `mcp:generate` | Generate audio and drum kits from your AI agent, spending your generation credits |

The first connection asks for `mcp:read` and `mcp:write`. The agent asks for
`mcp:generate` separately, with its own approval, the first time it
generates. The agent can read the source of your own projects but cannot
change it. It cannot publish modules, read your email or change your
account. Its access works at
`https://maruaudio.com/mcp` only and cannot be used with any other Maru API.

## Use a personal token

For a script, a CI job or a client that cannot open a browser to sign in:

1. Open **Settings → Access tokens** ([/account/tokens](https://maruaudio.com/account/tokens)).
2. Create a token with only the agent permissions you need, "Read Maru
   guides, templates, and your Studio projects and their source from your AI
   agent", "Create Studio projects and sound banks in your account from your
   AI agent", and, to generate audio, "Generate audio and drum kits from your
   AI agent, spending your generation credits". Copy it; it is shown once.
3. Send it as a header from your client:

```json
{
  "mcpServers": {
    "maru": {
      "url": "https://maruaudio.com/mcp",
      "headers": { "Authorization": "Bearer syn_your_token" }
    }
  }
}
```

Treat the token like a password and revoke it when you no longer need it.

The same token works with the hosted API the CLI uses: every tool on this
server is also `POST https://maruaudio.com/api/v1/ops/<name>` without the
`maru_` prefix, with `{"input": {…}}` as the body, and a signed-in `maru`
runs them the same way (`maru project list`, `maru build list`,
`maru audio generate`).

## Test the connection

Ask your agent "Which Maru tools do you have?" It should name tools starting
with `maru_`, such as `maru_list_studio_projects`. Then ask "What am I working
on in Maru?" and check the answer against your projects in Studio.

To check the server without an agent, open
[`/mcp/tools.json`](https://maruaudio.com/mcp/tools.json): the same tool list a connected agent
sees, with each tool's input schema and the permission it needs. The
[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) also
connects to `https://maruaudio.com/mcp` and runs the same sign-in, so you can
call each tool by hand:

```bash
npx @modelcontextprotocol/inspector
```

Choose **Streamable HTTP**, paste the URL, and connect.

## Disconnect

Open **Settings → Access tokens**. Each connected agent is listed under the name
it registered with; revoke it to cut access at once. Removing the connector in
your agent alone does not revoke Maru's side, so do both. To reconnect later,
add the URL again.

Sign-in lasts while you keep using the agent: access renews in the background
for up to 30 days without use, after which the agent asks you to approve again.

## Troubleshooting

Agent apps rarely show a useful error. What each symptom usually means:

| Symptom | Cause and fix |
| --- | --- |
| Adding the connector spins, then fails | The URL is incomplete. Copy `https://maruaudio.com/mcp` again, including `/mcp`. |
| The option to add a connector is missing | You are on a phone app, or ChatGPT developer mode is off. Use a computer; for ChatGPT, turn on developer mode first. |
| The Maru page says the request is no longer valid | The approval page sat open too long or was used twice. Start connecting again from the agent. |
| The agent says it needs the `mcp:write` permission | The connection was approved without write access. Disconnect, reconnect, and approve both permissions. |
| A tool fails mid-conversation and asks you to connect | Access expired or was revoked. Reconnect from the agent's connector settings. |
| Connected, but the agent never uses Maru | Turn Maru on for this conversation (Claude's tools menu, ChatGPT's **+** menu), then ask about your Maru projects by name. |
| An error mentions a diagnostic id (`mcp_…`) | Include that id when you contact support: it identifies the exact request. |