Calling Operations

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.

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:

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

1
{
2
  "pathParams": {
3
    "conversationId": "conv_AAAAAAAAAAAAAAAAAAAAAA"
4
  },
5
  "body": {
6
    "text": "Now download the resulting CSV"
7
  }
8
}

Use bctrl_get_operation before a structured write:

1
{
2
  "operationId": "conversations.messages.create"
3
}

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

Other content types

Multipart upload operations support:

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:

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.