> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Calling Operations

> Call generated BCTRL MCP tools with the correct request envelope.

Each documented public API operation is available as a generated MCP tool. The
tool name starts with `bctrl_`; punctuation in the operation ID becomes an
underscore.

```text
conversations.messages.create → bctrl_conversations_messages_create
runs.trace.list               → bctrl_runs_trace_list
tools.calls.create            → bctrl_tools_calls_create
```

## Request envelope

Generated tools separate HTTP concerns instead of flattening unrelated values:

| Field        | Use                                                                               |
| ------------ | --------------------------------------------------------------------------------- |
| `pathParams` | Values embedded in the URL path. Required when the operation has path parameters. |
| `query`      | Query-string parameters.                                                          |
| `headers`    | Documented headers such as `BCTRL-Subaccount-Id` or `Idempotency-Key`.            |
| `body`       | JSON request body matching the referenced OpenAPI schema.                         |

For example, sending an Agent another message uses both path parameters and a
JSON body:

```json
{
  "pathParams": {
    "conversationId": "conv_AAAAAAAAAAAAAAAAAAAAAA"
  },
  "body": {
    "text": "Now download the resulting CSV"
  }
}
```

Use `bctrl_get_operation` before a structured write:

```json
{
  "operationId": "conversations.messages.create"
}
```

Its response identifies the method, path, parameters, content type, and exact
request and response schemas.

## Other content types

Multipart upload operations support:

```text
fields       Multipart text fields
fileBase64   Base64-encoded file content
fileUrl      HTTP(S) URL to fetch as file content
filename     Uploaded filename
contentType  Uploaded file MIME type
```

Binary downloads accept `returnBase64: true` when the client needs the response
inside JSON.

SSE operations accept:

```text
maxEvents  1–200 events to collect
timeoutMs  100–30000 milliseconds to collect
```

An MCP call collects a bounded portion of the stream; it does not remain
subscribed forever. Pass the last received sequence through the stream
operation's `query.after` value when you need subsequent events.

## Generic executor

`bctrl_call_operation` accepts the same envelope plus `operationId`. Prefer the
generated operation tool when available because its name and description give
the model better context. Use the generic executor as a fallback for dynamic
operation selection.