Using the Pilea API and MCP

Want to push feedback in from your own product, build custom automations, or pull backlog items straight into your code editor? That’s what the Pilea API and MCP server are for.

The Pilea API

The public API lives at:

https://api.getpilea.com/api/v1

Interactive reference docs are at api.getpilea.com/api/v1/docs.

It’s a full API with TypeScript support, covering five resources: workspaces, mentions, backlog items, customers, and tags - with read and, per resource, write access. Common uses:

• Push feedback directly from your product
• Create custom workflows and automations

Creating an API key

API keys are created at the organization level.

1. In Pilea, go to Settings → API & MCP.
2. Create a new key and give it a name.
3. Choose its access level: Full access, or Custom access with specific scopes - workspaces:read, mentions:read/mentions:write, backlog-items:read/backlog-items:write, customers:read/customers:write, tags:read/tags:write.
4. Copy your key now - you won’t be able to see it again.

💡 Tip: Use Custom access with the narrowest scopes that do the job. A script that only pushes feedback needs mentions:write, not full access.

Authenticating

Pass your key in the X-Api-Key header on every request:

X-Api-Key: your_api_key_here

Targeting a workspace

API keys belong to your organization, but most work happens inside a workspace. Pass the X-Workspace-Id header on your requests to target a specific workspace.

The MCP server

Pilea ships an MCP (Model Context Protocol) server, so AI editors can work with your Pilea data directly. The package is @pilea-insights/mcp.

It works with Claude Code, Claude Desktop, Cursor, VS Code, and Windsurf.

With MCP connected, your AI editor can access backlog items, insights, and customer feedback - and pull dev-ready backlog items with full context, including the attached mentions and customer quotes, straight into the IDE. Instead of pasting a ticket description into your editor, your coding agent reads the item plus the actual customer evidence behind it.

What you’ll need

• Node.js 18 or newer
• A Pilea API key (see Creating an API key above - the MCP server uses the same keys)

Claude Code

Run this in your terminal:

claude mcp add pilea --env PILEA_API_KEY=your_api_key_here --env PILEA_API_BASE_URL=https://api.getpilea.com/api/v1 -- npx @pilea-insights/mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add Pilea under mcpServers:

{
  "mcpServers": {
    "pilea": {
      "command": "npx",
      "args": ["@pilea-insights/mcp"],
      "env": {
        "PILEA_API_KEY": "your_api_key_here",
        "PILEA_API_BASE_URL": "https://api.getpilea.com/api/v1"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor, VS Code and Windsurf

These use the same mcpServers block as Claude Desktop - drop it into the MCP config your editor points at (in Cursor, Settings → MCP → Add new MCP server), then reload the editor.

Settings

Variable	Required	What it does
PILEA_API_KEY	Yes	Your organization-level API key
PILEA_API_BASE_URL	Yes	https://api.getpilea.com/api/v1
PILEA_WORKSPACE_ID	No	Target one workspace by public ID (e.g. ws_abc123), or all for every workspace. Omit to use the org default - you can also switch at runtime by asking your agent to change workspace.

What your agent can do

Once connected, your agent can list and search backlog items, open an item with its full customer context, create and update items, browse and create mentions, manage customers and tags, switch workspaces, and suggest commit messages that link work back to the Pilea item.

ℹ️ Note: Since the key is only shown once at creation, store it somewhere safe (like your team’s secrets manager) before closing the dialog. If you lose it, create a new key.

API or MCP - which one?

• API - You’re writing code: pushing feedback from your product, syncing data into internal tools, building automations.
• MCP - You’re working in an AI editor and want backlog items with full customer context available to your coding agent.

They’re complementary, and both are governed by the same organization-level keys and scopes.

Next: How integration syncing works