---
name: penbox-api
description: Reach the parts of the Penbox public API that the curated tools do not cover, through the penbox_api_search, penbox_api_details and penbox_api_call tools. Use when a curated tool refuses, is missing, or when the user names an endpoint of the Penbox API.
---

# Use the Penbox public API through MCP

Three generic tools expose the whole documented API. They follow the published OpenAPI specification at `https://docs.penbox.io/api-reference`.

## Order of operations

1. `penbox_api_search` with a few keywords. Empty query lists everything. Each row is an operation such as `GET /forms`.
2. `penbox_api_details` with that exact operation string. It returns the parameters, the body schema and the response shape.
3. `penbox_api_call` with `operation`, plus `path_params`, `query` or `body` as documented.

Never skip step 2 on an operation you have not called in this conversation. The details are the contract.

## Prefer the curated tool

A search row may carry `prefer: <tool>`. That curated tool covers the operation with extra guards. Use it. The passthrough refuses the mutations a curated tool already covers, and names it.

## Limits

- Creating a workspace or a member is not possible through MCP.
- Responses over 50 KB are truncated. Narrow the query or paginate.
- Every call runs as the signed-in user, with that user's rights. A refusal from the API is final.

## Reading the results

The API speaks JSON:API. A resource has `id`, `type`, `attributes` and `relationships`. Follow ids through `relationships` to reach related resources.

## Report

Tell the user which operation ran and what came back, in business words. Do not paste raw JSON unless asked.