Sosta MCP-Server

Connector documentation.

Sosta exposes its tenant-data via the Model-Context-Protocol (MCP) so ChatGPT, Claude, Gemini and other MCP-compatible clients can work with setcards, presence, shifts and the hosted-site directly. This server exposes 20 tools — read tools (setcards, shifts, site blocks) and write tools (propose / confirm / cancel shifts, create / update / delete / reorder site blocks, publish / unpublish, verify custom domain). Tool availability per connector depends on its permission profile.

20 live tools
1.0 protocol version
POST /mcp endpoint
Bearer auth scheme

Endpoint

The MCP-Server accepts JSON-RPC 2.0 requests over HTTP at https://mcp.sosta.app/mcp. Streaming uses Server-Sent-Events as defined in the MCP Streamable HTTP Transport spec. 

POST https://mcp.sosta.app/mcp
Authorization: Bearer sk_sosta_live_...
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Per-tenant API-keys are generated in the Manager UI under Connectors. Tools the key does not have permission for are omitted from the tools/list response — clients only see what they can call.

Tools

All 20 tools — read and write — live on production. Permission-gating is per-tool.

Info

server_info

info read-only always-on

Returns information about the Sosta MCP server and the current authenticated tenant.

No inputs.

Setcard

list_setcards

setcard read-only requires list_setcards

List all RosterEntries (setcards) for this tenant. Returns up to 200, ordered by archive-status then name.

Inputs (1)
  • includeArchived boolean — Include archived setcards (default false).

get_setcard

setcard read-only requires get_setcard

Get details for a specific RosterEntry by ID. Includes presence (Plan 0037) and link-status.

Inputs (1)
  • rosterEntryId stringrequired

search_setcards

setcard read-only requires search_setcards

Search tenant setcards by name (case-insensitive contains-match). Optional filter for presently-active setcards (Plan 0037 presence-window covers now). Returns up to 50 matches with metadata.

Inputs (4)
  • query stringrequired — 1-60 chars, contains-match on showName.
  • presentOnly boolean — Default false. If true, filter to PERMANENT or presence-window contains now.
  • includeArchived boolean — Default false.
  • limit number — 1..50, default 20.

Shift

list_shifts

shift read-only requires list_shifts

List shifts for this tenant. Filter by status or upcomingOnly. Returns up to 100.

Inputs (2)
  • status string — PROPOSED | CONFIRMED | ACTIVE | COMPLETED | CANCELLED
  • upcomingOnly boolean — Filter to startAt >= now.

get_active_shifts

shift read-only requires get_active_shifts

Returns all shifts currently in ACTIVE state (startAt <= now <= endAt). 'Who is in the house right now'.

No inputs.

set_presence

shift mutation requires set_presence

Set the presence window of a roster entry (setcard): presenceStartAt/presenceEndAt (ISO-8601 with offset, or null to clear), optional presenceTimeWindowStart/End (HH:mm) and membershipType. Tenant-scoped — the roster entry must belong to the authenticated tenant. Pure roster scheduling like the Manager UI /anwesenheit — no matching, no assignment, no customer touch. Audit-logged.

Inputs (6)
  • rosterEntryId stringrequired — Setcard-ID des Workers.
  • presenceStartAt stringrequired — ISO-8601 with offset, or null to clear.
  • presenceEndAt stringrequired — ISO-8601 with offset, or null to clear. Must be >= presenceStartAt.
  • presenceTimeWindowStart string — HH:mm or null. Omit to leave unchanged.
  • presenceTimeWindowEnd string — HH:mm or null. Omit to leave unchanged.
  • membershipType string — PERMANENT | ROTATING | EVENT | TRIAL. Omit to leave unchanged.

propose_shift

shift mutation requires propose_shift

Tenant-side shift proposal. Status PROPOSED_BY_TENANT — worker must confirm via Talents-PWA. Conflict-detection prevents overlapping shifts for the same worker.

Inputs (4)
  • rosterEntryId stringrequired — Setcard-ID des Workers.
  • startAt stringrequired — ISO-8601 with offset.
  • endAt stringrequired — ISO-8601 with offset, > startAt.
  • notes string — Optional. Max 2000 chars. Keine Konditionen (Sosta speichert keine Gagen).

confirm_shift

shift mutation requires confirm_shift

Tenant confirms a worker-proposed shift. Status moves from PROPOSED_BY_WORKER / WAITING_TENANT to CONFIRMED.

Inputs (1)
  • shiftId stringrequired

cancel_shift

shift mutation requires cancel_shift

Cancel a shift from any non-terminal state. Reason is required and stored in the audit log. Worker gets notified via Talents-PWA.

Inputs (2)
  • shiftId stringrequired
  • reason stringrequired — Begründung (1-500 chars).

Site

update_block

site mutation requires update_block

Mutate the content of a hosted-site block (e.g. change Hero-Headline, Body-Text, Opening-Hours). Tenant-scoped — block must belong to the authenticated tenant. Audit-entry is written. Use after list_blocks to discover block-IDs, or pass known block-IDs from the Manager UI.

Inputs (2)
  • blockId stringrequired
  • content objectrequired — Block-Content-Felder, abhängig vom Block-Type (HERO: { headline, subheadline, alignment }, TEXT: { body, heading }, etc.)

add_block

site mutation requires add_block

Append a new content-block to the tenant's hosted-site. Tenant-scoped. Audit-entry is written. If position is omitted, the block is appended at the end of the existing block-list.

Inputs (3)
  • blockType stringrequired — HERO | TEXT | IMAGE | SETCARD_GRID | CONTACT_FORM | OPENING_HOURS | GALLERY | ABOUT
  • content objectrequired — Initial content. Shape depends on blockType — siehe Boutique-v1 Template-Defaults.
  • position number — Optional. Default = end-of-list.

list_blocks

site read-only requires list_blocks

List all blocks of the tenant's hosted-site in display order. Use before mutating to discover block-IDs. Includes archived blocks if requested.

Inputs (1)
  • includeArchived boolean — Default false. If true, soft-deleted blocks are included.

check_publish_readiness

site read-only requires check_publish_readiness

Read-only check ob die Hosted-Site publish-bereit ist. Returns ready:bool + reasons[] (title_missing, no_active_blocks, custom_domain_tls_not_issued). Use this VOR request_publish — KI-Agent sieht was zu fixen ist ohne den Publish-Akt zu triggern.

No inputs.

delete_block

site mutation requires delete_block

Soft-archive a block (sets archivedAt). The block is hidden from the renderer but restorable via Manager UI. Audit-entry is written.

Inputs (1)
  • blockId stringrequired

reorder_blocks

site mutation requires reorder_blocks

Set the display order of all blocks. Pass blockIds[] in the new order — every ID must belong to the tenant and not be archived. Audit-entry is written.

Inputs (1)
  • blockIds string[]required — Array of block-IDs in the desired new order (1..50 entries).

update_site_meta

site mutation requires update_site_meta

Update site-level metadata: title, metaDescription, primaryColor (hex #RRGGBB), accentColor (hex). At least one field required. Tenant-scoped + audit-logged.

Inputs (4)
  • title string — 1-120 chars.
  • metaDescription string — Max 300 chars.
  • primaryColor string — Hex #RRGGBB.
  • accentColor string — Hex #RRGGBB.

request_publish

site mutation requires request_publish

Set hosted-site status to PUBLISHED after readiness-check (title, subdomain, ≥1 active block, TLS für custom-domain). Idempotent — returns ok wenn schon PUBLISHED. Subscription-Check ist TODO Plan 0031 (Phase-1: alle Tenants dürfen publishen). Audit-logged.

No inputs.

unpublish

site mutation requires unpublish

Take hosted-site offline (status → DRAFT, unpublishedAt timestamp). Subdomain delivers Sosta-branded 404 afterwards. Idempotent — returns ok if already DRAFT. Audit-logged.

No inputs.

verify_custom_domain

site mutation requires verify_custom_domain

Trigger DNS-CNAME-Lookup für configured customDomain → match gegen cname.sosta.app. Match: customDomainVerifiedAt + TLS-Status → PENDING. Mismatch: returns hint with actualTargets. Audit-logged.

No inputs.

Quick start

How to wire up your favourite AI client to the Sosta MCP-Server.

Claude Desktop

Add the MCP-Server to your claude_desktop_config.json under mcpServers. Use the @modelcontextprotocol/server-fetch bridge or any HTTP-MCP client. 

{
  "mcpServers": {
    "sosta": {
      "url": "https://mcp.sosta.app/mcp",
      "headers": {
        "Authorization": "Bearer sk_sosta_live_..."
      }
    }
  }
}

ChatGPT (Custom GPT)

Configure the Sosta MCP-Server as a tool source in the GPT-builder. ChatGPT bridges MCP via its tool-call protocol — paste the endpoint and bearer-token under Actions.

Gemini (Vertex AI Agent Builder)

Sosta's MCP-Server is reachable from Gemini Agents via the generic HTTP-tool wrapper. Register the endpoint, attach the bearer-token as a header, and the agent can call any permitted tool.

Custom client

Use the official @modelcontextprotocol/sdk (TypeScript) or python-sdk with the Streamable-HTTP-Transport. Sosta tracks the spec, you get standard ergonomics.

Rate limits & audit

Each API-key has a token-bucket rate-limit of 100 calls/hour and 1000 calls/day. Limits are charged per tool-call (read-tools cost less than write-tools), so a batched JSON-RPC request is counted per contained call. Exceeding the limit returns HTTP 429 with JSON-RPC error -32002. Every tool-call writes an audit-entry with key-ID, tool-name, result (ok/error/rate_limited) and user-agent — owners can see the call-log in the Manager Connectors → Audit tab. Failed authentication is throttled and audited separately.