Connect an AI agent

Every gallery has a remote Model Context Protocol server. An MCP client (Claude, Cursor, Replit's Agent, or your own) connects to it and gets the gallery's tools — search, read, and, on a read-write connection, the writes — as thin verbs over the same /api/v1 operations the API reference documents. The database's row-level security is the boundary on every call, exactly as it is for the API.

The connect URL

One server per gallery, named by the gallery slug:

https://<host>/api/mcp/g/<gallerySlug>/mcp

Two query parameters narrow a connection; both only ever lower what the credential already allows.

• ?mode=read — only the read tools are offered. A look-but-don't-touch connection for research and reporting.
• ?toolsets=<group,group,…> — only the named domain groups are offered, for clients that load every tool up front and pay for the list in context. The groups are gallery (always included), artworks, artists, lists, publications, knowledge, contacts, tags, engagement, offers, deals, sales, invoices, inbox, campaigns, locations, shows, jobs, legal, consignments, and payables. An unknown name is a 400, never a silently narrower list.

Example: …/mcp?mode=read&toolsets=contacts,engagement.

Authenticate

The server accepts two credentials.

• An agent key. Mint a gpk_ key on the gallery's API settings page and send it as Authorization: Bearer gpk_…. A read-only key is the browse-only agent; a read-write key can do exactly what its scopes allow (see Authentication). This is the credential for a build-time or unattended agent, and it works for accounts with two-factor authentication enabled.
• Your own sign-in. A client that supports OAuth signs you in through the platform's authorization server and connects as you, with your in-app permissions. A tokenless request answers 401 with the metadata the client needs to start that flow.

A handful of tools read data that is private to a signed-in member — knowledge search, engagement signals, briefings, contact memory. They are offered only on a signed-in connection; an agent-key connection never sees them.

How writes are confirmed

Consequential writes are two-step so an agent cannot act on a guess. A single-target update or delete echoes the record's live expected_title or expected_name, and the server verifies it against the record before acting; an irreversible send requires confirm: true on a second call after the first call's preview. Clients that support form elicitation confirm through a native dialog instead. The server's own instructions, sent once per connection, tell the model to resolve records by search before changing them and to restate a preview in plain language before asking for approval.

Errors relay the API's problem details (see Errors): a 403 means the credential's own permissions forbid the action, not a transient failure.

What an agent reads

• The OpenAPI document at /api/v1/openapi.json — every operation, its parameters, request body, responses, and required scope, described for a reader who never sees the code. CORS-open.
• This documentation as Markdown — /docs/llms.txt indexes every guide with a link to its .md twin; /docs/llms-full.txt is the whole corpus in one fetch. The help center (/help/llms.txt) and the public site (/llms.txt) expose the same surfaces.
• The gallery's own vocabulary — the gallery://<slug>/schema MCP resource lists the enum terms (availability states, ownership, conditions, kinds) the tools filter and write by.
• The SDKs — the TypeScript SDK and its Python mirror are generated from the same document, so an agent writing code against the API gets typed operations with the same descriptions.

Where to start

• To build and host an app with an agent, see Build with Replit.
• To call the API directly with a key, see Getting started.
• Retries and safe re-sends: Idempotency.