Skip to Content

MCP / Developer reference

Build an MCP client

Transport, OAuth discovery, tool discovery, and error handling for developers.

For ChatGPT or Claude, use the connection guide. This page is for a custom MCP client.

Connection contract

SettingValue
Endpointhttps://app.vendita.io/api/mcp
TransportStreamable HTTP, stateless, with JSON responses enabled
AuthenticationOAuth access token issued for the connecting client
Token deliveryAuthorization: Bearer <access_token>
Resource metadatahttps://app.vendita.io/.well-known/oauth-protected-resource
Session IDNo server-managed MCP session ID

Use a maintained MCP client implementation for protocol negotiation and lifecycle messages. Do not send REST request bodies to the MCP endpoint.

Discover OAuth

An unauthenticated request returns HTTP 401 with a WWW-Authenticate header identifying the protected-resource metadata URL. Fetch that metadata, follow its authorization_servers value, and use the issuer’s discovery document.

The verified issuer advertises dynamic client registration, authorization-code and refresh-token grants, and PKCE S256. Register automatically, use PKCE S256, and complete the interactive authorization redirect. Discover endpoint values instead of hardcoding the underlying Supabase project URL.

The user approves the connection on Vendita’s consent screen. A browser-session token or a vk_live_... API key is not an MCP OAuth grant. The server requires the token to identify an OAuth client and carry a valid workspace and role.

Resource metadata currently advertises no custom Vendita scopes. OAuth identity scopes are separate from Vendita permissions; the user’s workspace role determines the latter.

Discover tools and resources

After MCP initialization, use tools/list for the live input schemas. Call whoami to verify the workspace, permissions, and current toolset. Compare tool names with your cached inventory and refresh when they differ.

The tool reference is a task index. The live tools/list result is authoritative for argument schemas. Obtain UUIDs from list results; never construct record IDs from names.

Selling playbooks are exposed through resources/list and resources/read, with URIs under vendita://library/. Clients without resource support can use library_list, library_read, and library_search.

For example, after initialization, a tool call uses this JSON-RPC shape:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "whoami",
    "arguments": {}
  }
}

Send it through your authenticated MCP client. A successful result includes a text content block containing the workspace, role, permissions, and toolset as JSON. Do not treat that text block as an ordinary REST data envelope.

Handle results and failures

Tool results contain JSON text in an MCP content text block. A tool failure sets isError: true and returns an error object. A transport-level HTTP success therefore does not guarantee the tool succeeded.

Handle OAuth failures before invoking tools again. For application failures, read the error code and message and retain x-request-id from the response when available. Respect rate-limit retry guidance. Poll background simulations and CRM imports rather than treating their initial response as completion.

Preview/confirm proposals are specific to the operation and workspace. Persist the proposal ID, present its details to the user, and confirm only the reviewed action. Do not assume a general idempotency header exists for ordinary writes. See permissions and actions.

On this page