Cooperto MCP

A Model Context Protocol (MCP) server for the Cooperto.it API — the booking, contacts/loyalty, queue and venue management platform.

The server is spec-driven: it reads openapi.json and automatically generates one MCP tool for each of the API's ~40 operations. When the spec is updated, the tools update with it — no code to rewrite. This lets any MCP-compatible client (such as Claude) read and manage Cooperto data through natural language.

Features

• One tool per endpoint — e.g. Prenotazioni_ElencoByCodiceSede, Contatti_Crea, Coda_ConfermaArrivo.
• Model-friendly inputs — query and path parameters become flat tool fields; the JSON request body is flattened into readable fields.
• Secure token handling — the Authorization: Bearer <token> header is injected by the server, never exposed to the model as a parameter.
• Multi-tenant ready — each Cooperto client can use its own token, set per session or per call.

Requirements

• Node.js 18 or newer.
• A valid Cooperto.it API token (Bearer token issued by Cooperto.it).

Installation

The package is published on npm, so there is nothing to clone or build. Your MCP client downloads and runs it with npx.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "cooperto": {
      "command": "npx",
      "args": ["-y", "cooperto-mcp@latest"]
    }
  }
}

Then fully restart the app. The same configuration works on any machine — no local paths, no manual install.

Claude Code (CLI)

claude mcp add cooperto -- npx -y cooperto-mcp@latest

Authentication

Every Cooperto client has its own token. The server resolves it in this order of priority:

1. a token field passed in an individual tool call (one-off override);
2. a token set for the session via the cooperto_imposta_token tool;
3. the COOPERTO_API_TOKEN environment variable (server default).

Recommended: token per project

Keep a separate Claude project for each client and put its token in the project instructions, for example:

At the start of the conversation, call cooperto_imposta_token with token: <CLIENT_TOKEN> and cliente: <NAME>. Use only that token for all Cooperto calls.

This keeps every project scoped to a single client.

Token via environment variable

To avoid placing the token in chat, set it as a server environment variable in your client config:

{
  "mcpServers": {
    "cooperto": {
      "command": "npx",
      "args": ["-y", "cooperto-mcp@latest"],
      "env": { "COOPERTO_API_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Note: a token written into chat or project instructions remains in plain text within the conversation context. For sensitive use, prefer the environment-variable approach.

Privacy: personal data redaction

By default, the server hides personal data in responses (first name, last name, phone, email, address, date of birth, etc.) to minimise exposure of sensitive information to the language model. Operational fields such as dates, party size, table and venue names, codes and statuses are kept.

To include personal data when you actually need it:

• per call — pass includi_dati_personali: true in the tool arguments, or
• globally — set COOPERTO_INCLUDE_PII=1 in your client config.

Configuration (environment variables)

| Variable | Default | Description | |----------|---------|-------------| | COOPERTO_API_TOKEN | — | Default Bearer token (optional; can also be set per session or per call). | | COOPERTO_INCLUDE_PII | 0 | Set to 1 to include personal data in responses. | | COOPERTO_TIMEOUT_MS | 30000 | Per-request timeout, in milliseconds. | | COOPERTO_MAX_RETRIES | 2 | Automatic retries on timeouts, rate limits (429) and server errors (5xx). | | COOPERTO_BASE_URL | API default | Override the API base URL. | | COOPERTO_IPV4_ONLY | 0 | Set to 1 to force IPv4 (useful on networks without IPv6 routing). |

Available endpoint groups

| Group | Example tools | |----------------|-------------------------------------------------------------------------------| | Sedi | Sedi_Elenco, Sedi_ElencoOrari | | Prenotazioni | Prenotazioni_ElencoByCodiceSede, Prenotazioni_Crea, Prenotazioni_Aggiorna, Prenotazioni_AggiornaStato, Prenotazioni_OrariModulo | | Contatti | Contatti_Elenco, Contatti_Crea, Contatti_SaldoPuntiByCodiceContatto, Contatti_AggiungiPuntiCard, coupons, tags, movements | | Coda | Coda_ElencoByCodiceSede, Coda_Crea, Coda_ConfermaArrivo | | FidelityCard | FidelityCard_Elenco | | Wifi | Wifi_Login |

⚠️ Write operations

Many tools modify real data (create/update/delete bookings, add/remove loyalty points, redeem coupons). When using the server conversationally, keep this in mind: consider testing against a demo venue first, and keep manual confirmation of write tools enabled in your client.

Disclaimer

This is an unofficial, community-maintained client for the Cooperto.it API. It is not affiliated with or endorsed by Cooperto.it. "Cooperto" and related marks belong to their respective owners. Use at your own risk.

License

Released under the MIT License.