Skip to main content

​
Managing Piper with Claude Code

You can connect Claude Code to Piper via the Model Context Protocol (MCP). Once connected, you can manage agents, search knowledge, run test conversations, and more — directly from your terminal.

​
Prerequisites

  • Claude Code installed
  • 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 Code”) 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.

​
Step 2: Add Piper to Claude Code

Run the following command in your terminal: 
claude mcp add --transport http piper https://api.letpiper.com/mcp/ \
  --header "Authorization: Bearer <your-token>"
Replace <your-token> with the token you copied in Step 1.
This saves the MCP server config to ~/.claude/settings.json. You can also add it manually by editing the file directly — see Manual configuration below.

​
Step 3: Verify the connection

Start a new Claude Code session 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 Code + Piper

Once connected, Claude Code can help you:
  • Run agents — send test messages and review responses
  • Check session history — inspect transcripts, tool calls, and token usage
  • Manage scenarios — create and update evaluation scenarios
  • Search files — query your knowledge documents with semantic search
  • Edit documents — update content, bookmarks, and configuration
See the MCP Tools Reference for the full list of available tools.

​
Manual configuration

If you prefer to edit the config file directly, add the following to ~/.claude/settings.json: 
{
  "mcpServers": {
    "piper": {
      "type": "http",
      "url": "https://api.letpiper.com/mcp/",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
Restart Claude Code after editing the file.

​
Troubleshooting

Claude says it can’t find Piper tools Verify the server is configured by running claude mcp list. If “piper” isn’t listed, re-run the claude mcp add command from Step 2. Authentication errors Check that your token hasn’t expired and that the header value is Bearer <token> (with “Bearer ” prefix). You can update the config with: 
claude mcp remove piper
claude mcp add --transport http piper https://api.letpiper.com/mcp/ \
  --header "Authorization: Bearer <new-token>"
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.