Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PINGEN_SCOPESNoSpace-separated scopes: letter batch email ebill template webhook organisation_read.
PINGEN_ENV_FILENoPath to an env file with the configuration keys, used when not set in the process environment.
PINGEN_CLIENT_IDYesClient ID from your Pingen developer app. Needed when a tool actually fetches a token; listing tools works without it.
PINGEN_GRANT_TYPENoOAuth grant type: client_credentials or authorization_code; invalid values fail at startup.client_credentials
PINGEN_TOKEN_FILENoAccess/refresh token storage location, always outside the repo.<user config dir>/pingen-mcp/tokens.json
PINGEN_ENVIRONMENTNoPingen environment: production or staging (see hosts below).production
PINGEN_API_BASE_URLNoResource API base URL override, mainly for tests.
PINGEN_REDIRECT_URINoRegistered redirect URI for the authorization-code grant; auth-code only.
PINGEN_CLIENT_SECRETYesClient secret from your Pingen developer app. Needed when a tool actually fetches a token; listing tools works without it.
PINGEN_IDENTITY_BASE_URLNoIdentity (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

CapabilityDetails
tools
{
  "listChanged": true
}
logging
{}
prompts
{
  "listChanged": true
}
resources
{
  "subscribe": false,
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
batches_listB

List batches. GET /organisations/{organisationId}/batches

page_number/page_limit map to page[number]/page[limit]; query keys (sort, filter, q, include, fields[...]) pass through verbatim.

batches_createB

Create a new batch. POST /organisations/{organisationId}/batches

payload is the full JSON:API document (CreateBatchPOST), sent verbatim.

batches_showC

Get details of a batch. GET /organisations/{organisationId}/batches/{batchId}

query keys (fields[batches]) pass through verbatim.

batches_editB

Edit a batch. PATCH /organisations/{organisationId}/batches/{batchId}

payload is the full JSON:API document (BatchEditPATCH), sent verbatim.

batches_deleteB

Delete a batch. DELETE /organisations/{organisationId}/batches/{batchId}

The spec marks a required JSON:API request body for this DELETE (schema BatchDeleteDELETE); payload is sent verbatim.

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

payload is the full JSON:API document (one of the BatchSendChannel* schemas), sent verbatim.

batches_eventsB

Get a collection of batch events. GET /organisations/{organisationId}/batches/{batchId}/events

page_number/page_limit map to page[number]/page[limit]; query keys (language, sort, filter, q, include, fields[...]) pass through verbatim.

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 query; page_number/page_limit map to page[number]/page[limit].

deliveries_ebills_createB

Create a new ebill. POST /organisations/{organisationId}/deliveries/ebills

payload is the full JSON:API document, sent through unchanged.

deliveries_ebills_showB

Get details of an ebill. GET /organisations/{organisationId}/deliveries/ebills/{ebillId}

query keys (include, fields[...]) pass through verbatim.

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 {"redirect_url", "status_code"} envelope without following the redirect.

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 query.

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 {"redirect_url", "status_code"} envelope without following the redirect.

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 query; page_number/page_limit map to page[number]/page[limit].

deliveries_emails_createB

Create a new email. POST /organisations/{organisationId}/deliveries/emails

payload is the full JSON:API document, sent through unchanged.

deliveries_emails_showB

Get details of an email. GET /organisations/{organisationId}/deliveries/emails/{emailId}

query keys (include, fields[...]) pass through verbatim.

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 {"redirect_url", "status_code"} envelope without following the redirect.

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 query.

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 {"redirect_url", "status_code"} envelope without following the redirect.

users_showA

Get details of the authenticated user. GET /user

query keys (fields[users]) pass through verbatim.

user_associations_listA

Get collection of associations of the authenticated user.

GET /user/associations

page_number/page_limit map to page[number]/page[limit]; query passes extra query parameters (sort, filter, q, include, fields[...]) through verbatim.

organisations_indexB

Get collection of organisations. GET /organisations

page_number/page_limit map to page[number]/page[limit]; query passes extra query parameters (sort, filter, q, fields[organisations]) through verbatim.

organisations_showC

Get details of an organisation. GET /organisations/{organisationId}

query keys (fields[organisations]) pass through verbatim.

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 fields_file_uploads argument maps to the query parameter fields[file_uploads] (which attributes of file_uploads to return) and is omitted from the request when not given.

letters_listB

List letters. GET /organisations/{organisationId}/deliveries/letters

Paginated collection. page_number maps to page[number] and page_limit to page[limit]; query keys (sort, filter, q, include, fields[...]) pass through verbatim.

letters_createC

Create a new letter. POST /organisations/{organisationId}/deliveries/letters

payload is the full JSON:API document (LetterCreatePOST) and is sent unchanged as the request body.

letters_showA

Get details of a letter. GET /organisations/{organisationId}/deliveries/letters/{letterId}

Returns the JSON:API document for a single letter, unchanged. query keys (include, fields[...]) pass through verbatim.

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

payload is the full JSON:API document (LetterSendPATCH) and is sent unchanged as the request body.

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 {"redirect_url": ..., "status_code": 302} so the caller can fetch the binary themselves.

letters_price_calculatorB

Calculate price for a letter configuration. POST /organisations/{organisationId}/deliveries/letters/price-calculator

payload is the full JSON:API document (LetterPriceCalculatorPOST) and is sent unchanged as the request body.

letters_eventsB

Get a collection of letter events. GET /organisations/{organisationId}/deliveries/letters/{letterId}/events

Paginated collection. page_number maps to page[number] and page_limit to page[limit]; query keys (language, sort, filter, q, include, fields[...]) pass through verbatim.

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 {"redirect_url": ..., "status_code": 302} so the caller can fetch the image themselves.

organisations_letters_events_deliveredB

Get a collection of all delivered events. GET /organisations/{organisationId}/deliveries/letters/events/delivered

Organisation-wide, paginated collection. page_number maps to page[number] and page_limit to page[limit]; query keys (language, filter, q, include, fields[...]) pass through verbatim.

organisations_letters_events_issuesB

Get a collection of all issue events. GET /organisations/{organisationId}/deliveries/letters/events/issues

Organisation-wide, paginated collection. page_number maps to page[number] and page_limit to page[limit]; query keys (language, filter, q, include, fields[...]) pass through verbatim.

organisations_letters_events_sentB

Get a collection of all sent events. GET /organisations/{organisationId}/deliveries/letters/events/sent

Organisation-wide, paginated collection. page_number maps to page[number] and page_limit to page[limit]; query keys (language, filter, q, include, fields[...]) pass through verbatim.

organisations_letters_events_undeliverableA

Get a collection of all undeliverable events. GET /organisations/{organisationId}/deliveries/letters/events/undeliverable

Organisation-wide, paginated collection. page_number maps to page[number] and page_limit to page[limit]; query keys (language, filter, q, include, fields[...]) pass through verbatim.

webhooks_indexB

List organisation webhooks. GET /organisations/{organisationId}/webhooks

Pagination maps to page[number]/page[limit]; query keys (filter, q, include, fields[...]) pass through verbatim.

webhooks_createC

Create new webhook. POST /organisations/{organisationId}/webhooks

payload is the full JSON:API document (data/attributes), passed through unchanged.

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.1/5.0

Scored across 49 tools

Disambiguation4/5

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.

Naming Consistency3/5

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.

Tool Count2/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessOutdated data