MCP: connect your agent docs

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 explains what the server does; Workflows has prompts to try once you are connected.

Before you start

A Maru account. Sign in at maruaudio.com 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 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 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.

Claude (claude.ai and Claude Desktop)

Open Settings → Connectors.
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.
Name it Maru and paste https://maruaudio.com/mcp as the URL. Leave the advanced settings empty.
Choose Add, then Connect. A Maru page opens: sign in if asked, check the access, and choose Approve.
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.

Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
Back in Apps & Connectors, choose Create.
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.
Confirm that you trust the connector, then approve on the Maru page.
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.

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:

Open Settings → Access tokens (/account/tokens).
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.
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: the same tool list a connected agent sees, with each tool's input schema and the permission it needs. The MCP 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.