Skip to main content
Glama

Cluby MCP

by com.cluby.api
OverviewDiscussionsAdmin

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.

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.
secretNoReserved for calls from Cluby to your service, such as the article search. Generated when omitted and returned once.
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.
articleSearchUrlNoReserved: where Cluby will search your article catalogue once venues can map benefits to articles. Optional.
webhookEndpointIdNoInstead of `endpoint`: use one of the organization's existing endpoints as the channel.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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."
  2. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare idempotentHint and destructiveHint, so safety framing is covered. The description adds non-obvious behavior: admin role required, a connected app's token makes that app the owner, secrets are returned exactly once and must be surfaced to the user, and partial-update semantics ('only the fields sent change') — all beyond the structured fields.

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?

Front-loaded with the core verb, prerequisite, and cardinality, then the endpoint/webhookEndpointId branch. Dense but every sentence carries a distinct fact; the packed single paragraph is the only minor readability cost.

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

Completeness4/5

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

For an 8-parameter tool with nested endpoint and capabilities objects and no output schema, the description covers ownership, prerequisites, secret lifecycle, and partial-update behavior. What's missing is any signal about what the call returns besides the generated secrets, which matters given there is no output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 8 parameters in depth; baseline is 3. The description adds the create-versus-adopt distinction between `endpoint` and `webhookEndpointId` and flags the one-time secret return, but leaves capabilities, articleSearchUrl, and enabled to the schema.

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?

States a specific verb pair (create or update) and resource (the organization's POS connection) and clarifies upsert semantics and one-per-org cardinality. An agent can separate it from get_pos_connection / delete_pos_connection and from create_webhook_endpoint, which the description implicitly routes to via `webhookEndpointId` adoption.

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?

Gives an admin-role prerequisite and an explicit either/or rule: use `endpoint` to create or edit the event channel versus `webhookEndpointId` to adopt an existing endpoint. It does not explicitly say when to prefer get_pos_connection first or which sibling to use for endpoint management, so it falls short of full when/when-not coverage.

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

All Cluby MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources