HTTP and MCP transports

This guide covers the browser use supervisor's restricted service protocol. The company integration instead uses /halfspan/v1, including /halfspan/v1/mcp; see How Halfspan works and Company setup.

Restricted merchant, bank, and broker services share the same authorization and transaction handlers. HTTP uses resource endpoints; MCP uses stateless Streamable HTTP at /mcp. Both require a restricted service bearer token created by the trusted runtime. Neither can use the owner session cookie or create a grant.

Operation	HTTP	MCP tool
Read capabilities	GET /api/v1/capabilities	`capabilities`
Read observation	GET /api/v1/observation	`observation`
Submit a report	POST /api/v1/turns	`submit_turn`
Get decision	GET /api/v1/decision	`decision`
Execute	POST /api/v1/operation	`execute`

The HTTP capabilities response contains service, version, and actionCatalog. The MCP capabilities tool returns the catalog array itself.

MCP request

Use an MCP client so initialization and protocol negotiation are handled correctly. Requests go to the exact service origin, such as http://127.0.0.1:4302/mcp for the bank. The following is the tool-call envelope after initialization:

12345POST /mcp HTTP/1.1
Host: 127.0.0.1:4302
Authorization: Bearer <restricted-session-token>
Content-Type: application/json
Accept: application/json, text/event-stream

123456789{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "decision",
    "arguments": {}
  }
}

MCP response

Tool results contain JSON serialized inside a text content item. A session with no submitted turn returns:

123456789101112{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"decision\":null,\"permit\":null}"
      }
    ]
  }
}

Parse the text item as JSON only after checking the MCP error envelope and result.isError. HTTP transport errors can occur before a tool result exists. GET /mcp returns 405 because this service uses stateless POST requests.

Tool arguments

capabilities, observation, and decision accept {}. submit_turn takes { "proposal": <TurnProposal> }, while HTTP POST /api/v1/turns takes the proposal directly. execute takes:

123456789{
  "permitId": "66666666-6666-4666-8666-666666666666",
  "action": {
    "kind": "service",
    "operationId": "bank.beneficiary",
    "args": {}
  },
  "idempotencyKey": "example-read-1"
}

The ID above is illustrative. Copy the current action and permit from the real decision. Unlike HTTP, MCP carries permitId and optional idempotencyKey in tool arguments rather than headers. The result is the same execution receipt schema shown in the HTTP reference, serialized in the text content item.

Native WebMCP remains conditional on browser support and a native actuation interface. It is not emulated by this MCP endpoint.

Ask AI about this page