MCP Server

Punchline's external API is also available as MCP tools through punchline-mcp — a local stdio server, published to npm, that your MCP client (Claude Code, Cursor, Claude Desktop, …) runs with npx. Authorization is entirely server-side: the tools you get depend on the API key you configure, and every call is bound by the same scopes and rate limits as the REST endpoints.

Install

Requires Node.js ≥ 18 on the machine running the MCP client. With the Claude Code CLI:

claude mcp add punchline --env PUNCHLINE_API_KEY=pnchl_live_... -- npx -y punchline-mcp

Or with the generic MCP client JSON config:

{
  "mcpServers": {
    "punchline": {
      "command": "npx",
      "args": ["-y", "punchline-mcp"],
      "env": { "PUNCHLINE_API_KEY": "pnchl_live_..." }
    }
  }
}

Environment variables

Variable	Required	Default	Notes
PUNCHLINE_API_KEY	yes	—	A pnchl_live_... project key or a pnchl_user_... user provisioning key. Sent as X-Punchline-Key.
PUNCHLINE_BASE_URL	no	http://proding.co:8050	Punchline API origin.

Any other key prefix, or a missing key, makes the server exit at startup with a config error on stderr.

Key types and tools

The server registers a different tool set depending on the key prefix. A single instance only ever exposes one set — to give an agent both capabilities, register the server twice under two names with two different keys (e.g. punchline and punchline-provisioning).

Project key (pnchl_live_...)

Issued by a project admin from project settings — the same key the External Ticket API uses.

Tool	Description
create_ticket	Create a ticket. reporter_email is required. Supports idempotent retries via idempotency_key.
list_tickets	List tickets visible to the key (own tickets, or the whole project with read:all). Paginated.
get_ticket	Fetch one ticket by display id (e.g. ACM-7).
update_ticket	Change a ticket's workflow status and/or customer-facing public summary.
add_communication	Post a customer-facing communication on a ticket.
whoami	Introspect the configured key: project, key name, scopes, last use. Useful for self-diagnosing 403s.
get_changelog	Recent externally-visible ticket changes for the project.

User provisioning key (pnchl_user_...)

Minted from your own Settings page — the same key the Project Provisioning API uses.

Tool	Description
create_project	Provision a new Punchline project. Returns the project and a one-time project API key — store it immediately; it is never shown again.

Scopes and rate limits

Nothing is relaxed for agents. Project keys carry the same read:own / read:all / write:own / write:all scopes as the REST API, enforced server-side per call — a key lacking the required scope gets a 403 tool error. Rate limits are also identical: a 429 surfaces in the tool error together with its Retry-After value.

Troubleshooting

Symptom	Cause / fix
Server exits immediately at startup	PUNCHLINE_API_KEY missing, or its prefix is neither pnchl_live_ nor pnchl_user_. Check the env block of your MCP config.
Tool error starting with 403	Valid key, but it lacks the scope the action needs. Run whoami to see the key's scopes; ask a project admin to widen them.
Tool error starting with 429	Per-key rate limit exceeded. Honor the Retry-After seconds in the error.
Expected tool is missing	The other key type is configured — tool sets are per key prefix (see above).