Sharetribe MCP Server

Sharetribe

Operator-level surface for a Sharetribe marketplace. Every tool runs as the marketplace operator across the entire tenancy — there is no per-user scoping at this level. Users sign up via the marketplace front-end (Marketplace API), not through this surface; create-user is intentionally absent because Sharetribe does not expose it on the Integration API.

Resource hierarchy

• Marketplace — the tenancy. One per credential pair. Carries name, description, currency.
• Users — accounts on the marketplace. State is active, pendingApproval, banned, or deleted. Each user has a permission set controlling whether they can post listings, initiate transactions, and read marketplace content.
• Listings — offers (products / services / bookable assets). State is draft, pendingApproval, published, or closed. Listings carry a price Money object (amount in minor units + ISO 4217 currency), an availabilityPlan for time-based bookings, and free-form publicData / privateData / metadata extended-data objects.
• Transactions — purchases or bookings against a listing. Each transaction runs a transaction process (e.g. default-booking/release-1) which defines the allowed states and transitions. A transaction's lastTransition tells you where it is in the process.
• Availability exceptions — per-listing overrides on top of the listing's availabilityPlan. Block out holidays with seats=0; add extra capacity with seats>=1.
• Stock — per-listing inventory for purchase processes. Two write surfaces: set_stock is compare-and-set (race-safe); create_stock_adjustment is unconditional signed delta.
• Stock reservations — read-only allocations created automatically by purchase-process transactions during checkout.
• Events — append-only audit log of every mutation across the tenancy.

Pattern: combined get_* tools

Read tools that target a list-able resource accept an optional id:

• No id → query the collection with page + per_page (default 25, max 100), plus resource-specific filters.
• With id → fetch the single entity. The same include (JSON:API side-load) applies on both branches.

include accepts a comma-separated string or a list — both "author,images" and ["author","images"] work.

Pattern: combined upsert_listing

sharetribe_upsert_listing selects POST listings/create (no id) vs POST listings/update (with id) automatically. On create, title and authorId are required and state must be published or pendingApproval. On update, every field is a partial overwrite; extended-data objects merge at the top level and top-level null keys are removed.

Money objects

Sharetribe represents money as {amount: <integer>, currency: <ISO 4217>}. Amount is in minor units — {amount: 1590, currency: "USD"} is $15.90, not $1,590. Always pass minor units when creating or updating prices, and always interpret returned amounts as minor units.

Pagination semantics

Sharetribe pagination is integer page (1-indexed) plus perPage, NOT an opaque cursor token. The wrapper normalizes list responses to {items, page, per_page, total, total_pages, has_more, next_page, included} so callers can iterate without parsing meta themselves.

The events stream is the exception: it advertises paginationUnsupported: true and returns total: null / total_pages: null / has_more: null. Walk it with createdAtStart + createdAtEnd windows or with the startAfterSequenceId forward cursor.

Transaction transitions

Transactions are state machines. To move a transaction along its process, call sharetribe_transition_transaction with the transaction id and the transition name (e.g. transition/accept, transition/cancel, transition/mark-delivered). The transition's params shape depends on the process definition — consult the marketplace's transaction process. Set speculative=true to validate a transition and produce the resulting transaction shape WITHOUT committing; useful for previewing line-item math before charging.

State-transition operations on listings and users

• sharetribe_close_listing / sharetribe_open_listing — hide / un-hide a listing without deleting. Reversible.
• sharetribe_approve_listing — only relevant when the marketplace requires operator approval; otherwise listings reach published on create.
• sharetribe_approve_user — moves a user from pendingApproval to active.
• sharetribe_update_user_permissions — operator-level allow/deny on postListings, initiateTransactions, read. Effect is immediate.

Operational order

1. Confirm the marketplace tenancy answers (get_marketplace) before anything credential-sensitive.
2. Discover the relevant author when working with listings — get_users first, capture the user id, then create / query listings filtered by authorId.
3. For booking flows, confirm the listing's availabilityPlan and any availability_exceptions in the booking window before transitioning a transaction.
4. For purchase flows, check current stock with get_listings (include=currentStock) before transitioning; use set_stock (CAS) for absolute updates and create_stock_adjustment for incremental deltas.
5. Use get_events as the canonical audit source after any operator mutation — events surface what actually happened upstream, not what the API call appeared to do.

Gotchas

• No user create. Sharetribe Integration API does not expose users/create; users sign up via the Marketplace API / front-end. Tools assume the user already exists.
• No image upload on this surface. The Integration API has no image upload endpoint. To attach images to a listing, the image UUIDs must come from the Marketplace API or the Sharetribe Console; images: [<uuid>, ...] on upsert_listing references them by id.
• No user delete on this surface either. No users/delete endpoint exists on the Integration API. User deletion is a marketplace-admin-console operation. To soft-disable a user from the Integration API, use update_user_permissions to deny postListings / initiateTransactions / read.
• Transitions can be permission-gated. Some processes restrict certain transitions to specific actors (customer-only, provider-only). Operator transitions go through unconditionally; if you see an upstream permission/denied error, the process definition is gating the transition rather than auth failing.
• expand=true is on by default for every write tool — the response is the full updated entity, not just the id. Set expand=false to opt into a smaller response.
• Closed-listing edits. A closed listing can still be updated (upsert_listing with id) but will not become visible until open_listing is called.
• Events are returned OLDEST-FIRST. get_events page 1 is the oldest events on the marketplace, not the newest. There is no descending sort. To answer "most recent N events", pass createdAtStart=<recent ISO timestamp> to narrow the window, or walk the stream with startAfterSequenceId until exhausted and read the tail. Do NOT call page-1 results "the most recent".
• set_stock is CAS-only — oldTotal is REQUIRED. Sharetribe rejects compare_and_set calls without oldTotal. Read current stock first via get_listings(id=<listing>, include='currentStock') and pass that value as oldTotal. If you don't have the current value or don't want a race-safe write, use create_stock_adjustment with a signed quantity instead — that endpoint is unconditional and incremental.
• All time-window arguments require explicit timezone. ISO-8601 timestamps passed to availability tools, stock-adjustment queries, transaction filters, and event windows MUST include a Z suffix or full UTC offset (e.g. +01:00). Naive timestamps are rejected with HTTP 400. When converting local times, account for DST yourself — UK in May is BST (UTC+1), so 9am UK = 08:00:00Z.