Provider proxy requests.

Choosing an interface

Proxy requests let you call provider methods that have no separate tool. They do not provide arbitrary HTTP access to any address. The connection and connector configuration determine the provider, credentials and base address. For some connectors the origin comes from the connection and undergoes egress validation.

Discovering a mirror endpoint

1. Retrieve GET /v1/connectors/{connectorId}/endpoints with tools:read. Filters: q, group, include_removed, cursor, limit.
2. Select an endpoint and request GET /v1/connectors/{connectorId}/endpoint?method=GET&path=.... path is the catalog template; encode it as a query value.
3. Read input_schema, output_schema, risk, sensitive, idempotent, paging and descriptor_digest. The input schema contains exact vendor fields; the format depends on the provider.
4. Fill in parameters and call its call_url with the described method.

Complete discovery and mirror contract. An endpoint ID consists of a method and path template. A removed entry may appear with include_removed=true, but cannot be executed. An endpoint does not automatically become an MCP tool.

Mirror: request and response

curl "https://ctx4.me/v1/api/amocrm/api/v4/leads/7" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY" \
  -H "Context4-Connection-Id: $CONTEXT4_CONNECTION_ID"

This is a GET request example applicable when the endpoint is in your catalog and the account can access the deal. Obtain the origin and keys from your environment. Bodyless methods have no body; for JSON writes, send vendor JSON directly. Mirror supports GET, POST, PUT, PATCH, DELETE; HEAD returns 405 and executes nothing.

The path mirrors the provider path after /v1/api/{connectorId}/. Send / literally or encode the entire vendorPath as one segment. A slash within a parameter value is %2F, or %252F when encoding the entire path. It is permitted only within a parameter of a known template; . and .. parts are prohibited.

Query parameters and declared vendor headers are validated against the input schema. Arrays use repeated names or a delimiter according to the descriptor; unknown query parameters and repeated scalar parameters are rejected. Do not assume every incoming header is forwarded to the provider.

Calls require executions:write, including GET. Context4-Connection-Id is required; a different connector's connection or a revoked connection produces a platform conflict. An unknown endpoint returns 404 before an upstream request; invalid vendor parameters return 400 before execution creation.

The response preserves the provider's HTTP status and JSON body, and permitted etag/retry-after headers. Context4-Origin: provider distinguishes it from a platform error; Context4-Execution-Id associates the call with an execution. A platform error has Context4-Origin: platform and problem JSON. Do not treat every 403 as a policy error: check the origin.

The mirror catalog includes operations that accept and return JSON. Multipart, form bodies, arbitrary bytes and redirect-only downloads are not promised. An unavailable provider, timeout or non-JSON response can produce 503. Each mirror call is a new request, even with a repeated Idempotency-Key.

Raw Composio proxy

POST /compat/context4/v1/api/v3.1/tools/execute/proxy accepts:

{
  "connected_account_id": "UUID of the selected connection",
  "endpoint": "/api/v4/leads",
  "method": "GET",
  "parameters": [
    { "name": "limit", "type": "query", "value": 10 }
  ]
}

Substitute a real UUID. method: GET, POST, PUT, DELETE, PATCH, HEAD. endpoint is a relative path from the connector's API base, starting with /. parameters is an array of objects with name, type (header or query) and string/numeric value; in is accepted instead of type. Optional body is JSON. Repeating a name in this legacy array replaces its previous value; for vendor arrays, prefer mirror with an explicit serialization schema.

The result is a JSON envelope {status, data, headers}. The compat request's own HTTP status differs from upstream status. Policy refusal returns 403, quota returns 429 and an unavailable account returns 404; permanent input/provider rejection maps to a validation error, transient failure to 503.

When user_id is supplied, the selected account is checked for usability by that principal. Optional borrowers narrows the owner set to the listed users and the principal; it does not remove the tenant boundary. With multiple accounts, choose connected_account_id explicitly. Session proxy uses its pinned account and session restrictions.

Security and retry boundaries

Absolute URLs, //host, traversal, backslashes, raw fragments and control characters are prohibited. Raw proxy does not accept encoded slashes to bypass a template. Connected-service credentials are inserted by the server: do not send a provider token through proxy.

Caller headers Authorization, Proxy-Authorization, Cookie, Cookie2, x-api-key are prohibited. Transport control headers (base-url-override, connection-id, provider-config-key, retries, retry-on, decompress, forward-headers-on-redirect, nango-*) are also rejected. Hop-by-hop headers are removed. A Context4 bearer authenticates to Context4 and does not become a provider credential.

Raw proxy bypasses the tool wrapper schema while retaining tenant, policy, quota, rate limit and audit checks. This does not promise access to every endpoint regardless of connector and transport capabilities. Check the provider's documentation and operation availability. After a write timeout, verify the outcome: absence of a response does not prove absence of an effect.