Connecting the MCP

The Agent MCP runs at https://mcp.heymantle.com/agent. The fastest way to wire it up to your AI tool is to run add-mcp, an open-source CLI that detects your installed coding agents and writes the right config for each one.

Quick install (recommended)

Run this from your terminal:

npx add-mcp https://mcp.heymantle.com/agent

The CLI auto-detects which AI tools you have installed (Claude Code, Claude Desktop, Cursor, VS Code, Codex, OpenCode, Gemini CLI, Goose, Zed, and more), prompts you to pick which one(s) to install Mantle into, and writes the right config for each.

The first time your AI tool tries a Mantle action, it'll open a browser window for OAuth approval. Approve in Mantle and you're connected.

Useful flags

• -y: skip prompts and install to detected agents
• -g: install globally instead of project-scoped
• -a <agent>: install only for a specific agent (repeatable, e.g. -a claude-code)
• --all: install to every supported agent

Examples:

# Install for Cursor and Claude Code, skip prompts
npx add-mcp https://mcp.heymantle.com/agent -a cursor -a claude-code -y

# Install everywhere, globally, no prompts
npx add-mcp https://mcp.heymantle.com/agent --all -g -y

Manual install

If you'd rather configure your AI tool by hand, add this to your client's MCP config file:

{
  "mcpServers": {
    "mantle": {
      "url": "https://mcp.heymantle.com/agent"
    }
  }
}

Where to put it:

Restart your client and the first Mantle tool call will trigger the OAuth flow.

Authentication

OAuth 2.1 (recommended)

OAuth ties access to your Mantle user account. Permissions follow your role, you can revoke access from settings, and you don't have to manage a long-lived secret. Modern MCP clients handle the OAuth flow automatically: the first time you use a Mantle tool, the client opens a browser window for you to approve.

API key (for headless setups)

Use an API key for scripted integrations or server-side agents that can't open a browser. Create one at Settings → API Keys in the Mantle web app, scope it to the permissions your agent needs, and pass it as a Bearer token:

{
  "mcpServers": {
    "mantle": {
      "url": "https://mcp.heymantle.com/agent",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Or with add-mcp:

npx add-mcp https://mcp.heymantle.com/agent --header "Authorization: Bearer your-api-key-here"

Use OAuth for anything interactive. Use an API key only for headless / scheduled jobs that can't open a browser.

Pick an agent

The Agent MCP works on top of the Agents you've already configured in Mantle. Each agent has its own mandate, tool list, codebases, and autonomy settings. Once connected, your AI tool will:

1. Call list_agents to see what's available
2. Call select_agent to start a session with one
3. Use that agent's tools for the rest of the conversation

You can switch agents mid-conversation by calling select_agent again. If you don't pick one explicitly, the connection defaults to m, Mantle's general assistant.

Set autonomy (optional but recommended)

Each agent has a default autonomy setting that controls what it can do without human approval:

• Auto: approve everything, including mutations. Fine for read-only or low-stakes agents.
• Confirm high-risk: auto-approve safe mutations, queue risky ones (sending emails, deleting data, charging customers) for approval.
• Confirm mutations: auto-approve reads, queue every write for approval.
• Confirm all: queue everything. Useful when you're getting started and want to see what your agent is doing.
• Custom: approve / require-confirm specific tools by name.

When an action needs approval, it shows up at Agents → Pending Actions in the Mantle web app. You'll get a notification, you review the proposed call, and you approve or reject.

Verifying the connection

Once connected, ask your AI tool something simple:

"What agents do I have available in Mantle?"

If the tool comes back with a list of your agents, the connection is working. If you get an auth error, double-check the URL and (for API keys) the scope you assigned.

Available scopes

If you're using an API key, scope it to what your agent actually needs:

OAuth grants the full set by default unless you specify scopes when registering the client.

What's next

• Walk through a real session: from connect to completed work
• Configure an agent for your team
• Back to the Agent MCP overview