# Transports

## REST

Base: `https://maison-labs.com`. Paths are listed per tool (always `/api/v1/...`). GET/DELETE inputs travel as path and query parameters (query strings are coerced by the input schema: numbers, booleans, comma-separated arrays); POST/PUT/PATCH take a JSON body. `POST /api/v1/tools/{name}` calls any tool with the input object as the body.

## MCP (Streamable HTTP)

Endpoint `https://maison-labs.com/mcp`. Headers: `x-api-key`, `content-type: application/json`, `accept: application/json, text/event-stream`.

1. `POST` an `initialize` request without `mcp-session-id`; the response header carries the session id.
2. `POST notifications/initialized`, then `tools/list` — the list is already filtered to your key.
3. `tools/call` with `{ name, arguments }`. Results: `content[0].text` is the JSON output and `structuredContent` the same object; failures return `isError: true` with `{ error, code, details }` in `structuredContent`.
4. `DELETE` with the session header to close.

Client configuration (Claude Desktop / Claude Code and similar):

```json
{ "mcpServers": { "maison": { "type": "http", "url": "https://maison-labs.com/mcp", "headers": { "x-api-key": "<key>" } } } }
```

## A2A (JSON-RPC 2.0)

Agent card: `https://maison-labs.com/.well-known/agent.json`; endpoint `https://maison-labs.com/a2a`. Skills are the tool catalogue.

- `tasks/send` runs one tool synchronously. Name it with a data part `{ "type": "data", "data": { "tool": "<name>", "input": { … } } }` (or `metadata.tool`). A text-only message is answered by `send_message` for `metadata.clientId` (or the `x-client-id` header). The completed task's artifact carries the output as a data part.
- `tasks/get` reads a task back (only by the user who created it). `tasks/cancel` always answers TaskNotCancelable — nothing stays in flight.
- Tool failures are JSON-RPC errors with `data.status` (the HTTP status REST would answer) and `data.code`.