pingen-mcp-server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PINGEN_SCOPES | No | Space-separated scopes: letter batch email ebill template webhook organisation_read. | |
| PINGEN_ENV_FILE | No | Path to an env file with the configuration keys, used when not set in the process environment. | |
| PINGEN_CLIENT_ID | Yes | Client ID from your Pingen developer app. Needed when a tool actually fetches a token; listing tools works without it. | |
| PINGEN_GRANT_TYPE | No | OAuth grant type: client_credentials or authorization_code; invalid values fail at startup. | client_credentials |
| PINGEN_TOKEN_FILE | No | Access/refresh token storage location, always outside the repo. | <user config dir>/pingen-mcp/tokens.json |
| PINGEN_ENVIRONMENT | No | Pingen environment: production or staging (see hosts below). | production |
| PINGEN_API_BASE_URL | No | Resource API base URL override, mainly for tests. | |
| PINGEN_REDIRECT_URI | No | Registered redirect URI for the authorization-code grant; auth-code only. | |
| PINGEN_CLIENT_SECRET | Yes | Client secret from your Pingen developer app. Needed when a tool actually fetches a token; listing tools works without it. | |
| PINGEN_IDENTITY_BASE_URL | No | Identity (tokens) base URL override, mainly for tests. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for the Pingen API (programmable physical mail, email and eBill dispatch). Every tool mirrors one documented operation of the official Pingen OpenAPI spec; responses are JSON:API documents passed through unchanged.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| batches_listB | List batches. GET /organisations/{organisationId}/batches
|
| batches_createB | Create a new batch. POST /organisations/{organisationId}/batches
|
| batches_showC | Get details of a batch. GET /organisations/{organisationId}/batches/{batchId}
|
| batches_editB | Edit a batch. PATCH /organisations/{organisationId}/batches/{batchId}
|
| batches_deleteB | Delete a batch. DELETE /organisations/{organisationId}/batches/{batchId} The spec marks a required JSON:API request body for this DELETE
(schema BatchDeleteDELETE); |
| batches_cancelC | Cancel a batch. PATCH /organisations/{organisationId}/batches/{batchId}/cancel No request body. |
| batches_sendB | Send a batch. PATCH /organisations/{organisationId}/batches/{batchId}/send
|
| batches_eventsB | Get a collection of batch events. GET /organisations/{organisationId}/batches/{batchId}/events
|
| organisations_batches_statistics_detailsC | Get statistics of a batch. GET /organisations/{organisationId}/batches/{batchId}/statistics |
| deliveries_ebills_listB | Get a collection of ebills. GET /organisations/{organisationId}/deliveries/ebills Extra query parameters (sort, filter, q, include, fields[...]) pass
through verbatim via |
| deliveries_ebills_createB | Create a new ebill. POST /organisations/{organisationId}/deliveries/ebills
|
| deliveries_ebills_showB | Get details of an ebill. GET /organisations/{organisationId}/deliveries/ebills/{ebillId}
|
| deliveries_ebills_deleteC | Delete a eBill. DELETE /organisations/{organisationId}/deliveries/ebills/{ebillId} |
| deliveries_ebills_sendB | Send an eBill. PATCH /organisations/{organisationId}/deliveries/ebills/{ebillId}/send Sends the eBill immediately; the request carries no body. |
| deliveries_ebills_cancelB | Cancel an ebill. PATCH /organisations/{organisationId}/deliveries/ebills/{ebillId}/cancel Cancels a pending ebill; the request carries no body. |
| deliveries_ebills_fileA | Get file of ebill. GET /organisations/{organisationId}/deliveries/ebills/{ebillId}/file Answers 302 to the stored PDF; returns the |
| deliveries_ebills_eventsA | Get a collection of ebill events. GET /organisations/{organisationId}/deliveries/ebills/{ebillId}/events Extra query parameters (language, sort, filter, q, include, fields[...])
pass through verbatim via |
| deliveries_ebills_events_imageA | Get an image of an ebill event. GET /organisations/{organisationId}/deliveries/ebills/{ebillId}/events/{deliverableEventId}/image Answers 302 to the image; returns the |
| deliveries_emails_listA | Get a collection of emails. GET /organisations/{organisationId}/deliveries/emails Extra query parameters (sort, filter, q, include, fields[...]) pass
through verbatim via |
| deliveries_emails_createB | Create a new email. POST /organisations/{organisationId}/deliveries/emails
|
| deliveries_emails_showB | Get details of an email. GET /organisations/{organisationId}/deliveries/emails/{emailId}
|
| deliveries_emails_deleteC | Delete an email. DELETE /organisations/{organisationId}/deliveries/emails/{emailId} |
| deliveries_emails_cancelB | Cancel an email. PATCH /organisations/{organisationId}/deliveries/emails/{emailId}/cancel Cancels a pending email; the request carries no body. |
| deliveries_emails_fileB | Get file of email. GET /organisations/{organisationId}/deliveries/emails/{emailId}/file Answers 302 to the stored file; returns the |
| deliveries_emails_eventsB | Get a collection of email events. GET /organisations/{organisationId}/deliveries/emails/{emailId}/events Extra query parameters (language, sort, filter, q, include, fields[...])
pass through verbatim via |
| deliveries_emails_events_imageA | Get an image of an email event. GET /organisations/{organisationId}/deliveries/emails/{emailId}/events/{deliverableEventId}/image Answers 302 to the image; returns the |
| users_showA | Get details of the authenticated user. GET /user
|
| user_associations_listA | Get collection of associations of the authenticated user. GET /user/associations
|
| organisations_indexB | Get collection of organisations. GET /organisations
|
| organisations_showC | Get details of an organisation. GET /organisations/{organisationId}
|
| files_file_uploadB | Get details for file upload (upload registration/destination etc). GET /file-upload Registration metadata only: the server never proxies file bytes, so the
JSON:API response passes through unchanged. The optional
|
| letters_listB | List letters. GET /organisations/{organisationId}/deliveries/letters Paginated collection. |
| letters_createC | Create a new letter. POST /organisations/{organisationId}/deliveries/letters
|
| letters_showA | Get details of a letter. GET /organisations/{organisationId}/deliveries/letters/{letterId} Returns the JSON:API document for a single letter, unchanged.
|
| letters_deleteB | Delete a letter. DELETE /organisations/{organisationId}/deliveries/letters/{letterId} Answers 204; the client returns an empty document for empty bodies. |
| letters_sendC | Send a letter. PATCH /organisations/{organisationId}/deliveries/letters/{letterId}/send
|
| letters_cancelB | Cancel a letter. PATCH /organisations/{organisationId}/deliveries/letters/{letterId}/cancel No request body. Answers 202 once the cancellation is queued. |
| letters_fileA | Get file of letter. GET /organisations/{organisationId}/deliveries/letters/{letterId}/file Answers 302 to the rendered PDF; the redirect is NOT followed. Returns
|
| letters_price_calculatorB | Calculate price for a letter configuration. POST /organisations/{organisationId}/deliveries/letters/price-calculator
|
| letters_eventsB | Get a collection of letter events. GET /organisations/{organisationId}/deliveries/letters/{letterId}/events Paginated collection. |
| letters_events_imageA | Get an image of a letter event. GET /organisations/{organisationId}/deliveries/letters/{letterId}/events/{letterEventId}/image Answers 302 to the actual image; the redirect is NOT followed. Returns
|
| organisations_letters_events_deliveredB | Get a collection of all delivered events. GET /organisations/{organisationId}/deliveries/letters/events/delivered Organisation-wide, paginated collection. |
| organisations_letters_events_issuesB | Get a collection of all issue events. GET /organisations/{organisationId}/deliveries/letters/events/issues Organisation-wide, paginated collection. |
| organisations_letters_events_sentB | Get a collection of all sent events. GET /organisations/{organisationId}/deliveries/letters/events/sent Organisation-wide, paginated collection. |
| organisations_letters_events_undeliverableA | Get a collection of all undeliverable events. GET /organisations/{organisationId}/deliveries/letters/events/undeliverable Organisation-wide, paginated collection. |
| webhooks_indexB | List organisation webhooks. GET /organisations/{organisationId}/webhooks Pagination maps to |
| webhooks_createC | Create new webhook. POST /organisations/{organisationId}/webhooks
|
| webhooks_showB | Get details of a webhook. GET /organisations/{organisationId}/webhooks/{webhookId} |
| webhooks_destroyC | Delete a webhook. DELETE /organisations/{organisationId}/webhooks/{webhookId} |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 49 tools
Each tool maps to a distinct REST endpoint and the resource prefix (letters, emails, ebills, batches, webhooks, organisations) plus action suffix usually makes selection clear. A few pairs need care — organisation-wide event feeds (organisations_letters_events_sent) versus per-letter events (letters_events), and files_file_upload which actually only fetches upload metadata rather than uploading anything.
All names are snake_case and mostly follow a resource_action shape, but the verb vocabulary is inconsistent (list vs index, show vs get, delete vs destroy, edit vs update) and the ordering flips between resource-first (letters_list) and path-first (organisations_letters_events_delivered, files_file_upload). Readable, but not predictable enough for an agent to guess names.
49 tools is well beyond a comfortable working set for an agent, even though it mirrors a real API surface of three delivery channels times roughly ten operations each. Much of the weight comes from repetitive per-channel variants (file, events, events_image, send, cancel) that could be consolidated.
CRUD plus lifecycle actions (send, cancel, file, events, statistics) are covered for letters, emails, ebills and batches, along with organisations, user, associations and webhooks. Minor gaps: no webhook update or webhook delivery/event listing, no letter or email edit operation, and no price calculator for channels other than letters.