Skip to main content
Glama

Cluby MCP

Set POS connection

set_pos_connection
DestructiveIdempotent

Create or update the organization's POS connection (requires the admin role; one per organization). Called with a connected app's token the app becomes its owner. endpoint: { url, secret?, includes? } creates — or on a later call edits — the connection's event channel; webhookEndpointId adopts an existing endpoint instead. Generated secrets (secret for Cluby → POS calls, endpointSecret for a created endpoint) are returned once, so show them to the user. Only the fields sent change.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "set_pos_connection"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoYour product's name, as the organization sees it.
orgIdNoOrganization public id, the `id` field from list_orgs. Omit it when the API key reaches exactly one organization.
secretNoSigns Cluby's calls to your service — the article search — over their request line, the way events are signed. Generated when omitted and returned once; send your own to keep a copy.
enabledNo`false` pauses the connection and its channel. Your next PUT after reconnecting turns them back on.
endpointNoThe connection's event channel, the webhook endpoint that receives `smart_link.scanned`. Created with every include unless `includes` says otherwise; an endpoint created earlier keeps the includes it lists. `url` is required on the first call; later calls change only the fields sent.
capabilitiesNoWhat your POS can do with an action's answer.
articleSearchUrlNoYour article search, which Cluby calls live when a venue picks articles or looks at the ones it linked (the guide's "The article search"). Stored without being called; check it with POST …/pos-connection/test-article-search. Optional.
webhookEndpointIdNoInstead of `endpoint`: use one of the organization's existing endpoints as the channel.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / articleSearchUrl / description
      Previous value: -"Reserved: where Cluby will search your article catalogue once venues can map benefits to articles. Optional."New value: +"Your article search, which Cluby calls live when a venue picks articles or looks at the ones it linked (the guide's \"The article search\"). Stored without being called; check it with POST …/pos-connection/test-article-search. Optional."
    • changedInput schema / properties / secret / description
      Previous value: -"Reserved for calls from Cluby to your service, such as the article search. Generated when omitted and returned once."New value: +"Signs Cluby's calls to your service — the article search — over their request line, the way events are signed. Generated when omitted and returned once; send your own to keep a copy."
  2. Changed17 schema fields changed
    • changedInput schema / properties / articleSearchUrl / anyOf
      Previous value: -[
      -  {
      -    "format": "uri",
      -    "maxLength": 2048,
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "description": "A public HTTPS URL. Private, link-local and loopback addresses are refused, and redirects are not followed.",
      +    "format": "uri",
      +    "maxLength": 2048,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / articleSearchUrl / description
      Added value: +"Reserved: where Cluby will search your article catalogue once venues can map benefits to articles. Optional."
    • addedInput schema / properties / capabilities / description
      Added value: +"What your POS can do with an action's answer."
    • changedInput schema / properties / capabilities / properties / apply / default
      Previous value: -[
      -  "price",
      -  "percent_off",
      -  "manual"
      -]New value: +[
      +  "percent_off",
      +  "amount_off",
      +  "price",
      +  "free_item",
      +  "manual"
      +]
    • addedInput schema / properties / capabilities / properties / apply / description
      Added value: +"The `apply` kinds your POS executes on the open sale. Every kind by default; list fewer if it cannot execute some. Preview."
    • changedInput schema / properties / capabilities / properties / apply / items / enum
      Previous value: -[
      -  "price",
      -  "percent_off",
      -  "manual"
      -]New value: +[
      +  "percent_off",
      +  "amount_off",
      +  "price",
      +  "free_item",
      +  "manual"
      +]
    • addedInput schema / properties / enabled / description
      Added value: +"`false` pauses the connection and its channel. Your next PUT after reconnecting turns them back on."
    • addedInput schema / properties / endpoint / description
      Added value: +"The connection's event channel, the webhook endpoint that receives `smart_link.scanned`. Created with every include unless `includes` says otherwise; an endpoint created earlier keeps the includes it lists. `url` is required on the first call; later calls change only the fields sent."
    • addedInput schema / properties / endpoint / properties / enabled / description
      Added value: +"`false` stops deliveries without deleting the endpoint."
    • addedInput schema / properties / endpoint / properties / includes / description
      Added value: +"What each event carries beyond its own data: `profile`, `membershipCards`, `benefits`, `stampCards`, `items`. None by default; a POS connection's own endpoint gets all of them."
    • changedInput schema / properties / endpoint / properties / includes / items / enum
      Previous value: -[
      -  "profile",
      -  "membershipCards",
      -  "benefits",
      -  "stampCards"
      -]New value: +[
      +  "profile",
      +  "membershipCards",
      +  "benefits",
      +  "stampCards",
      +  "items"
      +]
    • addedInput schema / properties / endpoint / properties / name / description
      Added value: +"A label for lists and alerts. The URL's host by default."
    • addedInput schema / properties / endpoint / properties / secret / description
      Added value: +"The key events are signed with. Omit it to have one generated (`whsec_…`), returned once and never again. Use the whole string, prefix included, as the HMAC key. A new one replaces the old at once."
    • addedInput schema / properties / endpoint / properties / url / description
      Added value: +"A public HTTPS URL. Private, link-local and loopback addresses are refused, and redirects are not followed."
    • addedInput schema / properties / name / description
      Added value: +"Your product's name, as the organization sees it."
    • addedInput schema / properties / secret / description
      Added value: +"Reserved for calls from Cluby to your service, such as the article search. Generated when omitted and returned once."
    • addedInput schema / properties / webhookEndpointId / description
      Added value: +"Instead of `endpoint`: use one of the organization's existing endpoints as the channel."
  3. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With idempotentHint and destructiveHint already declared, the description adds substantial context: admin-role requirement, single-connection-per-org constraint, ownership transfer on token use, that generated secrets (`secret`, `endpointSecret`) are returned only once and must be surfaced to the user, and that 'only the fields sent change' — which importantly softens the destructiveHint by clarifying this is a partial update.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action, permission, and cardinality are front-loaded in the first sentence, and later sentences carry distinct facts. It is dense — semicolon-chained clauses about endpoint creation versus adoption — but essentially every clause earns its place; slight compression cost in readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter nested-object tool with no output schema, the description covers the gaps that matter most: it explains the one return value an agent must act on (once-only secrets), the create-vs-adopt channel choice, and partial-update semantics. Nothing critical to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter synthesis the schema cannot: `endpoint` creates-or-edits the event channel while `webhookEndpointId` adopts an existing endpoint instead, an explicit mutual exclusion. It also front-loads the shape of `endpoint` before the agent opens the nested object.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first clause names a specific verb pair and resource: 'Create or update the organization's POS connection'. It is immediately distinguishable from siblings get_pos_connection and delete_pos_connection, and the upsert nature (create now, edit on later calls) is explicit rather than inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real preconditions (admin role required, one connection per organization) and states that a connected app's token makes the app the owner. It also resolves the either/or between `endpoint` and `webhookEndpointId`. It does not say when to read the existing connection via get_pos_connection first, so no explicit sibling routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources