Calling a connector

Every connector — REST or RPC — is reached through the same three tools. They are exposed as native agent tools and over the MCP server. The flow is always: discover the catalog, read the service passport, then execute.

1

list_services — the catalog

Returns the connector catalog: a canonical key and one-line summary per service. Handshake-sized (~2–5 KB), so every session can start here. With connected accounts, each entry is tagged connected: true/false.

2

describe_service — the passport

Returns a structured passport for one service: its modules, common recipes (concrete VERB /path examples with body templates), rate limits, field hints, pagination hints, enums, response examples, and a version/ttl for client-side caching. Call it without a module for the index, then with a module for the full per-module spec.

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

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", module="statistics", method="GET", path="/api/v1/supplier/orders", query={"dateFrom": "2026-04-15"} )

connector_execute parameters

FieldTypeDescription
servicerequiredstringConnector key from list_services (for example wildberries). May carry an account suffix — see multi-account addressing below.
modulestringSub-area of the connector (statistics, content, …) as listed in the passport.
methodrequiredstringREST: the HTTP verb (GET/POST/…). RPC: the RPC method name.
pathstringREST: the request path. RPC: leave empty and pass the method name in method.
bodyobjectRequest body for write calls.
queryobjectQuery-string parameters for the call.
instance_idstringTarget a specific connected account when more than one is connected.

REST vs RPC

Connectors come in two shapes, and connector_execute handles both:

  • REST (most connectors) — pass module, an HTTP method, a path, and body/query.
  • RPC (for example bitrix24, the onec family) — leave path empty and pass the RPC method name in method.

The passport's recipes show the exact shape for each connector, so you rarely guess.

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; writes must name one, either via instance_id or a suffix on the service:

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 module returns a hard error with did_you_mean suggestions and the list of known_modules.
  • An unknown or mismatched path still proceeds, but attaches a soft path_did_you_mean hint plus an available_paths menu in the response metadata.
  • An unknown account returns UNKNOWN_INSTANCE with a candidates list.

Errors

Connector calls return the standard tool error contract — code, message, retryable, and an optional hint. Calls made over MCP carry no HTTP status code. See the MCP error table and Errors & rate limits.

Was this page helpful?