Skip to main content

​
Managing Piper with Claude

You can connect Claude Desktop to Piper via the Model Context Protocol (MCP). Once connected, you can use Claude to run agents, check job status, create scenarios, and manage your Piper workspace — all from a natural language conversation.

​
Prerequisites

  • Claude Desktop installed on your computer
  • A Piper account with at least one organization

​
Step 1: Create a Personal Access Token

  1. In the Piper dashboard, open Settings → API Tokens.
  2. Click Create Token.
  3. Give it a name (e.g. “Claude Desktop”) and select the organization(s) you want Claude to access.
  4. Choose an expiration (90 days recommended, or “Never” if you prefer).
  5. Click Create Token.
  6. Copy the generated token — you won’t be able to see it again.
  7. Copy the MCP Configuration snippet shown below the token.

​
Step 2: Add Piper to Claude Desktop

  1. Open Claude Desktop.
  2. Go to Settings → Developer → Edit Config to open claude_desktop_config.json.
  3. Paste the MCP configuration you copied from Piper into the mcpServers object. It will look like this:
{
  "mcpServers": {
    "piper": {
      "type": "http",
      "url": "https://api.letpiper.com/mcp/",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
  1. Save the file and restart Claude Desktop.
Every tool requires an org_id parameter. Claude will call list_organizations to discover your available organizations and include org_id automatically. If your token has access to multiple organizations, tell Claude which one you want to work with.

​
Step 3: Verify the connection

Start a new Claude conversation and ask:
“What agents do I have in Piper?”
Claude will use the Piper MCP server to list your agents. If you see your agents, the connection is working.

​
What you can do with Claude + Piper

Once connected, Claude can help you:
  • Run agents — start a job and monitor its progress
  • Check job history — see recent runs, outputs, and errors
  • Manage scenarios — create and configure test scenarios
  • Explore your workspace — list agents, channels, and organization settings

​
Troubleshooting

Claude says it can’t find Piper tools Restart Claude Desktop after editing the config file. Claude Desktop only loads MCP servers on startup. Authentication errors Check that your token hasn’t expired and that the Authorization header value is Bearer <token> (with “Bearer ” prefix). Multiple organizations Every tool requires an org_id parameter. Claude will call list_organizations to discover your available organizations and include org_id automatically. If your token grants access to multiple organizations, tell Claude which one you want to work with.