MCP tools & scopes

SnabbSajt exposes the owner's own business capabilities to AI clients (Claude, ChatGPT, Cursor, Codex) over the Model Context Protocol. It is an outbound, owner-authorized surface - a second front door to the same Convex business functions + authorization the app itself uses. No third-party code runs inside SnabbSajt. Owners manage it under Settings → Advanced → AI integrations.

Source: lib/mcp/server.ts (registry), convex/mcpTools.ts (tool layer), lib/mcp/scopes.ts (scopes), convex/mcp.ts (connections + token auth + activity).

Connection

• URL: https://snabbsajt.com/api/mcp
• Auth (two paths):

  • OAuth 2.1 (Claude / ChatGPT) - Clerk is the authorization server (discovery via RFC 9728 protected-resource metadata, dynamic client registration enabled); the client just signs in - no key to paste.

  • API token (Claude Code / Cursor / Codex / header clients) - Authorization: Bearer sajt_live_…. Only a SHA-256 hash + display prefix is stored; the plaintext is shown once. Claude Code one-liner:

    claude mcp add --transport http snabbsajt https://snabbsajt.com/api/mcp \
      --header "Authorization: Bearer sajt_live_…"

• A connection is scoped to one website (default) or the whole workspace.
• OAuth clients use the same https://snabbsajt.com/api/mcp endpoint. Clerk is verified at the MCP edge; a five-minute signed delegation then binds the verified OAuth client audience to one exact SnabbSajt connection. The server never accepts a caller-supplied profile id or guesses from the owner's newest one.

Scopes (least privilege, safe defaults)

Every tool re-checks the connection owner's live website role on each call, so a token can never exceed its creator's permissions, and revoking the owner's share neuters the token.

Tools

Reads (site:read): list_sites, get_site_overview, list_pages, get_page, list_draft_changes, get_brand, get_analytics_summary.

Draft writes (content:write - edit the draft only; publish to go live): update_section_text, update_page_seo, add_section, move_section, set_section_hidden, create_page, create_blog_post.

Advanced draft writes (content:write + the workspace's invite-only advanced-editor (Labs) grant - server-gated, fail-closed): get_section_json reads one section's full draft JSON (content, layout, rev); replace_section_content replaces a section's entire content with a validated JSON document of the same section type (pass the rev from get_section_json as clientRev - a stale rev is rejected so concurrent editor work is never silently overwritten); set_section_layout sets bounded layout tokens (width, vertical padding, hide on mobile/desktop). Without the Labs grant these tools return a logged denial; content is always re-validated against the section schema, so raw HTML/CSS can never enter through them.

Draft services and products (commerce:write): list_services, create_service, list_products, create_product, get_commerce_overview. These create draft records or return PII-free operations status. They neither send an invoice or charge a customer. prepare_publish_product is the one catalogue exception: it creates a five-minute reviewed plan for one exact product revision. A signed-in owner must approve it before confirm_pending_action can make that product public.

Business settings (settings:write): update_business_name. Live search visibility uses prepare_search_visibility and the reviewed owner-approval rail. Custom head code remains intentionally unavailable through MCP.

Domains (domain:write): list_domains reads connection and verification status. Buying, connecting, changing a primary address, and removal remain unavailable until they use reviewed owner-approved adapters.

Access (access:write): list_access returns the target site’s members and pending invitations. Sending or revoking access remains unavailable until it uses reviewed owner-approved adapters.

Publish (publish): publish_site deliberately fails closed. A host uses prepare_publish / prepare_unpublish to show the review card. The owner must then approve the exact plan in a signed-in SnabbSajt page before confirm_pending_action can redeem it. The plan is caller-bound, expires after five minutes, pins the reviewed site revision and can only be used once. Text-only MCP clients can edit drafts and prepare a review, but cannot redeem a public action.

Customer info (crm:read - personal data, off by default): list_leads, list_bookings, list_contacts.

AI generation (ai:generate - spends credits, off by default): planned - see roadmap below.

Most tools take an optional websiteId (omit it for a single-site connection; required for a workspace-scoped one). Call list_sites first to discover the available ids. Section/page ids come from list_pages / get_page.

Excluded (human-only): delete site/page, GDPR-erase a contact, billing changes, people management, domain purchase - never on the MCP surface.

Resources

Read-only context for the connection's default site, so a client can load state without a tool call: sajt://site/overview, sajt://site/pages, sajt://site/draft-changes, sajt://site/brand.

Prompts

Guided workflows: write_news_post, prep_for_launch, seasonal_update.

Rate limits & errors

• Rate limit: 120 calls/min per connection, 600/min per workspace.
• Tool result shape: { ok: true, data } on success; { ok: false, error } on an authorization/scope/validation failure (the failure is logged to Activity). Business-op failures throw and roll back (no partial write).
• Activity: every call records a one-line, PII-free summary, shown in the AI integrations settings tab (90-day retention).
• Reviewed actions: publish and unpublish plans are caller-bound, expire after five minutes, can be used once, and are garbage-collected after expiry.

Roadmap

ChatGPT writes normal website copy itself and applies it through draft tools; it does not spend SnabbSajt AI credits. ai:generate remains reserved for a future product-specific generation flow. The Apps SDK card layer is working for site overview and publish/unpublish review; broader CRM, operations, domain, access, and commerce adapters remain the next explicit implementation slice.

See also: Auth & permissions, For AI agents.