MCP binding

The first A2M binding is an MCP server. Any MCP client that supports remote servers can connect an agent to a market through it.

Transport

• MCP over Streamable HTTP, stateless, JSON responses.
• The agent authenticates the HTTP request with Authorization: Bearer <token>. Tools never take a token as an argument, so the credential never enters the model’s context.
• Without a valid bearer the server answers 401 with APEX_4001 and a WWW-Authenticate header. When OAuth is configured, that header carries resource_metadata pointing at the protected-resource document. See OAuth binding.
• Server instructions tell the model to prefer a2m_place_order, and that a PENDING_APPROVAL result means a human must approve.

Tools

Tool	Input	Annotations	Maps to
a2m_whoami	none	read-only	The agent this token belongs to
a2m_check	Intent	read-only	Dry run of every rule. Reserves nothing; cannot be sent
a2m_place_order	Intent	write, idempotent	Authorize; if ACCEPT or RESIZE, send the signed decision to the executor. Returns the verdict and, when sent, the order. The same intent_id never creates a second order. Forms beyond limit and market are accepted where the venue declares them
a2m_replace_order	Intent plus replaces	write, idempotent	Change a working simple order in place where the venue declares replace. Authorized as a new decision; the old order turns replaced when the venue confirms. Groups cannot be replaced
a2m_exercise	{ intent_id, venue, instrument, action }	write, idempotent	exercise a long option, or do_not_exercise it at expiry. Needs options level 2; a call also needs the strike cash. Nothing is reserved
a2m_submit_decision	{ decision, signature }	write, idempotent	Send an already signed ACCEPT or RESIZE, for example one produced by an approval
a2m_order_status	{ id } (client order id)	read-only	One of this agent’s orders, its fills and cost analysis
a2m_cancel_order	{ id } (client order id)	write	Ask the venue to cancel one of this agent’s working orders
a2m_approval_status	{ id } (approval id)	read-only	Whether a human approved or denied a PENDING_APPROVAL order
a2m_positions	{ venue? }	read-only	Open positions in the agent’s own venue accounts, read live from the venue, plus mandate usage against position_limit_notional
a2m_balances	{ venue? }	read-only	Account value, withdrawable cash and margin used in the agent’s own venue accounts, plus the executor’s last synced cash and buying power
a2m_open_orders	{ venue? }	read-only	Orders resting at the venue in the agent’s own accounts; the agent’s own orders carry their client_order_id
a2m_fills	{ limit?, venue? }	read-only	Recent executions in the agent’s own venue accounts, newest first; the agent’s own fills carry their client_order_id
a2m_quote	{ instrument, venue? }	read-only	Best bid and ask, mid and mark for an instrument the mandate allows; usable as reference_price
a2m_get_rules	none	read-only	The agent’s current trading rules, templates, and any pending rule-change request
a2m_search_instruments	{ q, venue?, limit? }	read-only	Search the symbols a venue lists, by symbol or name
a2m_update_rules	{ template } or { rules }	write	Submit a rule-change request. Nothing changes until the user approves it in the console; an agent cannot approve it

The read tools are scoped by the bearer: they only return accounts bound to the agent’s user, and a venue account shared by several agents shows its whole state, with the agent’s own orders and fills marked. Venues without these reads report supported: false.

The input schema of a2m_check, a2m_place_order and a2m_replace_order is the intent object the REST API decodes, field for field (a2m_replace_order also requires replaces), and the authorizer validates it as received.

Results

• A refusal from the authorizer or executor (a REJECT, or an HTTP error such as A2M_BAD_SIGNATURE) is returned as a tool result with isError: true and the error body as text, so the model can read it and act on it. It is not an MCP protocol failure.
• a2m_place_order returns verdict, code, message, approval_id, decision, signature and, when the order was sent, order.

Approval flow over MCP

1. a2m_place_order returns PENDING_APPROVAL and an approval_id.
2. Poll a2m_approval_status with the approval_id.
3. When it is approved, pass the signed decision exactly as returned to a2m_submit_decision. Changing any signed field makes it fail with A2M_BAD_SIGNATURE.

REST equivalents

The same objects are available over HTTP: GET /v1/whoami, POST /v1/check, POST /v1/authorize, POST /v1/actions, GET /v1/approvals/{id}, POST /v1/orders, POST /v1/orders/{id}/cancel, GET /v1/agent/orders/{id}, GET /v1/keys. A formal REST binding document is planned.