Calling a connector

The same tools discover connectors, describe their API contracts and run individual REST or RPC calls. They are available as native agent tools and through the MCP server. If the service and current passport are already available, go straight to the call.

list_services — the catalog

Returns the connector catalog. Over MCP it is the static registry services: [{name, summary, transport}] (about 16 000 characters) with no connectedness flag. The agent's native tool returns items (connected services with their cabinets and status as of as_of) and available (names of the whole catalog). A name in available means "the service exists", not "not connected".

describe_service — the passport

Returns a structured passport for one service. The index lists modules, call_template, critical_hints and recipe headlines. Pass module to read its endpoints, request templates, limits, pagination and response examples. An unknown module returns the index and _module_filter_warning with the valid options.

Reuse the full passport while its service, module, content and access scope still match. Read it again when the body is missing or the contract or access changes. version describes the response schema.

describe_service(service="wildberries") describe_service(service="wildberries", module="statistics")

connector_execute — the call

A single executor for any connector. Arguments are validated against the service schema before any outbound HTTP call.

connector_execute( service="wildberries", method="GET", path="/api/v1/supplier/orders", query={"dateFrom": "2026-04-15"} )

For a recurring workflow with an existing skill, call its Python entry point. In a native agent session with a Python sandbox, cw.connect() lets one cell read, filter and aggregate pages. Apply filters or batch requests documented by the vendor first, then return the requested result and coverage from Python.

connector_execute parameters

Field	Type	Description
servicerequired	string	Connector key from list_services (for example wildberries). The account is named by a suffix in this same string (`ozon:2`, `ozon:Top Zip`); there is no separate field for it. See multi-account addressing below.
module	string	REST: usually omitted, the module resolves from path; pass it only for a path not among the recipes. RPC: required (the method namespace, for example crm).
methodrequired	string	REST: the HTTP verb (GET/POST/…). RPC: the method name (crm.deal.list). Verb and path always go in separate fields.
path	string	REST: the path with concrete values (/api/v3/stocks/12); an object's own address from a response (meta.href) is accepted as is. RPC: empty string.
body	object \| array	POST/PUT/PATCH body, or the named arguments of an RPC method.
query	object	Query-string parameters; arrays are serialized for you.
files	object	Native agent tool only. Files to upload, keyed by the vendor's field name: an attachment or artifact id, or a sandbox path. An address, never base64: the platform encodes it.

REST vs RPC

Connectors come in two shapes, and connector_execute handles both:

REST (most connectors): an HTTP method, a path, and body/query; module resolves from the path.
RPC (for example bitrix24): module (the method namespace, for example crm), the method name in method (crm.deal.list), arguments in body, path empty.

The passport's call_template and recipes show the exact shape. An HTTP verb with a path sent to an RPC service is rejected with TOOL_VALIDATION_FAILED and an available_recipes menu.

Multi-account addressing

When an organization has connected more than one account for a service (several Ozon cabinets, for instance), address a specific one. A bare service name fans reads across all connected accounts (except services where a cross-cabinet total makes no sense, such as onec and moysklad: there reads name one too); writes must name one with a suffix on the service (the cabinet id or its label), inside the same service string:

connector_execute(service="ozon:Top Zip", method="POST", path="/v1/product/import", body={ ... })

Did-you-mean recovery

Calls don't fail silently on a near-miss. Recipes are examples, not a whitelist, so:

An unknown service returns a refusal with close keys in details.suggestions.
An unknown module returns TOOL_VALIDATION_FAILED with known_modules and suggestions, and so does a missing one where it is required (RPC), with the same list. On a REST call the module resolves from the path, so a wrong label does not break the call.
A path not among the recipes still proceeds, and an available_paths menu rides in the response metadata (and in the error, for example a 404). A verb the recipes for that path do not list is neither refused nor hinted at: the connector's verb table decides which verbs a path takes, and where that table is not closed the service answers itself.
An unknown connection returns UNKNOWN_INSTANCE with a candidates list (connection, label), and so does a write that named none while several are connected: same code, same list, because the recovery is the same one: take the ready connection address from candidates and pass it whole as service (service="ozon:2"). Over MCP the code is the same, and details.connector_code tells which of the two cases it was.

Errors

Connector calls return the standard tool error contract: code, message, retryable, and optional hint and details. Calls made over MCP carry no HTTP status code. See the MCP error table and Errors & rate limits. Cases worth telling apart:

No rights on the path (403). AUTH_SCOPE_MISSING: the key or token lacks a right that a new connection can grant. AUTH_SCOPE_NOT_GRANTABLE: the app's rights are fixed, retrying will not help. details name the path that was refused.
The cabinet's auth died. In chat the turn pauses on a reconnect card and resumes once the account is connected again.
Method retired by the vendor. When Wildberries or Ozon itself declares the method switched off (a Sunset header with a past date, or "this method is deprecated" in the body), the hint says never to call that path again and to find the successor in describe_service.