# Tools Reference (/aiway/mcp/reference/tools-reference)



The authoritative catalog of every tool the MCP connector exposes through `tools/call`: 11 core messaging tools plus 4 agent-bridge tools. For each tool you get its arguments, defaults, JSON Schema, a ready-to-run curl request, and the response shape.

## Overview [#overview]

The MCP connector advertises **15 tools** in its `tools/list` response and runs them through the single `POST /mcp` endpoint on the [shared HTTP server](/connectors/concepts/shared-http-server) (port `9090`, protocol version `2025-11-25`). The 11 core tools are always registered; the 4 agent-bridge tools appear only when the [A2A agent registry](/aiway/a2a) is present.

<Callout type="info">
  This page is the canonical argument and schema reference. The per-tool pages under [Tools](/aiway/mcp/tools) carry the same operations with examples in all nine languages. For the wire-level request/response forms see [Endpoints](/aiway/mcp/reference/endpoints); for the failure codes see [Error codes](/aiway/mcp/reference/error-codes).
</Callout>

## Tool summary [#tool-summary]

| #  | Tool                       | Category        | Required args             | Optional args                                                                                       |
| -- | -------------------------- | --------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| 1  | `queue_send`               | Queue           | `channel`, `body`         | `metadata`, `tags`, `delay_seconds`, `expiration_seconds`, `max_receive_count`, `dead_letter_queue` |
| 2  | `queue_receive`            | Queue           | `channel`, `max_messages` | `wait_timeout_seconds`                                                                              |
| 3  | `queue_peek`               | Queue           | `channel`, `max_messages` | *(none)*                                                                                            |
| 4  | `events_publish`           | Events          | `channel`, `body`         | `metadata`, `tags`                                                                                  |
| 5  | `events_store_publish`     | Events          | `channel`, `body`         | `metadata`, `tags`                                                                                  |
| 6  | `events_store_read`        | Events          | `channel`, `max_messages` | `from_sequence`, `from_time`                                                                        |
| 7  | `events_store_read_latest` | Events          | `channel`                 | `count`                                                                                             |
| 8  | `command_send`             | Command / Query | `channel`, `body`         | `timeout_seconds`, `metadata`, `tags`                                                               |
| 9  | `query_send`               | Command / Query | `channel`, `body`         | `timeout_seconds`, `metadata`, `tags`                                                               |
| 10 | `channel_list`             | Channel         | *(none)*                  | `type`, `pattern`                                                                                   |
| 11 | `channel_info`             | Channel         | `channel`, `type`         | *(none)*                                                                                            |
| 12 | `agent_list`               | Agent bridge    | *(none)*                  | `skill_tags`                                                                                        |
| 13 | `agent_info`               | Agent bridge    | `agent_id`                | *(none)*                                                                                            |
| 14 | `agent_send`               | Agent bridge    | `agent_id`, `message`     | `blocking`, `context_id`, `timeout_seconds`                                                         |
| 15 | `agent_query`              | Agent bridge    | `agent_id`, `method`      | `params`                                                                                            |

## Calling convention [#calling-convention]

Every tool is invoked the same way: a `tools/call` JSON-RPC request naming the tool and passing its `arguments` object. Only `name` and `arguments` change between tools.

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "<tool_name>",
      "arguments": { }
    }
  }'
```

Every successful `tools/call` returns a result with a `content` array of typed blocks — KubeMQ uses `text` blocks carrying the operation result as a string (often a JSON string). A tool-level failure sets `isError: true` in the same envelope; the JSON-RPC response itself still succeeds with HTTP `200`.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "isError": false
  }
}
```

<Callout type="warn">
  A `channel` that starts with the reserved prefix `_AGENTS_.` is rejected — see [Channel resolution](/aiway/mcp/guides/channel-resolution). Missing required arguments return a `-32602` Invalid Params JSON-RPC error, not an `isError` result.
</Callout>

## Queue tools [#queue-tools]

Durable, point-to-point queue messaging. See [Queue tools](/aiway/mcp/tools/queues) for language examples.

### queue\_send [#queue_send]

Send a message to a queue channel.

| Argument             | Type    | Required | Default | Description                                                               |
| -------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------- |
| `channel`            | string  | Yes      | —       | Target queue channel. Must not start with the reserved prefix `_AGENTS_.` |
| `body`               | string  | Yes      | —       | Message body content                                                      |
| `metadata`           | string  | No       | `""`    | Optional message metadata string                                          |
| `tags`               | object  | No       | `{}`    | Key-value tags for message classification                                 |
| `delay_seconds`      | integer | No       | `0`     | Delay before the message becomes visible. `0` = immediately available     |
| `expiration_seconds` | integer | No       | `0`     | TTL in seconds. `0` = no expiration                                       |
| `max_receive_count`  | integer | No       | `0`     | Max receives before dead-letter. `0` = unlimited                          |
| `dead_letter_queue`  | string  | No       | `""`    | Dead-letter queue channel name                                            |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "body"],
      "properties": {
        "channel": { "type": "string" },
        "body": { "type": "string" },
        "metadata": { "type": "string", "default": "" },
        "tags": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} },
        "delay_seconds": { "type": "integer", "minimum": 0, "default": 0 },
        "expiration_seconds": { "type": "integer", "minimum": 0, "default": 0 },
        "max_receive_count": { "type": "integer", "minimum": 0, "default": 0 },
        "dead_letter_queue": { "type": "string", "default": "" }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "queue_send",
      "arguments": {
        "channel": "example-queue",
        "body": "Hello from MCP",
        "metadata": "example-metadata",
        "tags": { "env": "dev", "source": "mcp-example" }
      }
    }
  }'
```

**Response** — a confirmation message in a single text block:

```json
{
  "content": [{ "type": "text", "text": "Message sent successfully to queue 'example-queue'" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; missing `channel`/`body` → `-32602`.

### queue\_receive [#queue_receive]

Receive and consume messages from a queue channel. This is a destructive read — returned messages are removed from the queue.

| Argument               | Type    | Required | Default | Description                                      |
| ---------------------- | ------- | -------- | ------- | ------------------------------------------------ |
| `channel`              | string  | Yes      | —       | Source queue channel                             |
| `max_messages`         | integer | Yes      | `1`     | Max messages to receive in a single call (1–100) |
| `wait_timeout_seconds` | integer | No       | `5`     | Long-poll wait time in seconds (1–60)            |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "max_messages"],
      "properties": {
        "channel": { "type": "string" },
        "max_messages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 },
        "wait_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "default": 5 }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "queue_receive",
      "arguments": { "channel": "example-queue", "max_messages": 5 }
    }
  }'
```

**Response** — a JSON array of received messages, serialized as the text payload:

```json
{
  "content": [{ "type": "text", "text": "[{\"body\":\"Hello from MCP\",\"metadata\":\"example-metadata\",\"tags\":{\"env\":\"dev\",\"source\":\"mcp-example\"}}]" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; a non-existent channel returns an empty result (no error).

### queue\_peek [#queue_peek]

Peek at messages without consuming them — a non-destructive read; messages stay in the queue.

| Argument       | Type    | Required | Default | Description                                    |
| -------------- | ------- | -------- | ------- | ---------------------------------------------- |
| `channel`      | string  | Yes      | —       | Source queue channel                           |
| `max_messages` | integer | Yes      | `1`     | Max messages to peek without consuming (1–100) |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "max_messages"],
      "properties": {
        "channel": { "type": "string" },
        "max_messages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "queue_peek",
      "arguments": { "channel": "example-queue", "max_messages": 5 }
    }
  }'
```

**Response** — same shape as `queue_receive`, but the messages remain in the queue:

```json
{
  "content": [{ "type": "text", "text": "[{\"body\":\"Hello from MCP\",\"metadata\":\"example-metadata\",\"tags\":{\"env\":\"dev\"}}]" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; a non-existent channel returns an empty result (no error).

## Events tools [#events-tools]

Pub/sub and the persistent events store. See [Events tools](/aiway/mcp/tools/events) for language examples.

### events\_publish [#events_publish]

Publish an ephemeral event (fire-and-forget; no persistence).

| Argument   | Type   | Required | Default | Description                             |
| ---------- | ------ | -------- | ------- | --------------------------------------- |
| `channel`  | string | Yes      | —       | Target events channel                   |
| `body`     | string | Yes      | —       | Event body content                      |
| `metadata` | string | No       | `""`    | Optional event metadata string          |
| `tags`     | object | No       | `{}`    | Key-value tags for event classification |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "body"],
      "properties": {
        "channel": { "type": "string" },
        "body": { "type": "string" },
        "metadata": { "type": "string", "default": "" },
        "tags": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "events_publish",
      "arguments": {
        "channel": "example-events",
        "body": "Event data",
        "metadata": "event-meta",
        "tags": { "source": "mcp-example" }
      }
    }
  }'
```

**Response:**

```json
{
  "content": [{ "type": "text", "text": "Event published successfully to channel 'example-events'" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; missing `channel`/`body` → `-32602`.

### events\_store\_publish [#events_store_publish]

Publish a persistent event to the events store. Stored events receive a monotonic sequence number.

| Argument   | Type   | Required | Default | Description                             |
| ---------- | ------ | -------- | ------- | --------------------------------------- |
| `channel`  | string | Yes      | —       | Target events-store channel             |
| `body`     | string | Yes      | —       | Event body content to store             |
| `metadata` | string | No       | `""`    | Optional event metadata string          |
| `tags`     | object | No       | `{}`    | Key-value tags for event classification |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "body"],
      "properties": {
        "channel": { "type": "string" },
        "body": { "type": "string" },
        "metadata": { "type": "string", "default": "" },
        "tags": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "events_store_publish",
      "arguments": {
        "channel": "example-events-store",
        "body": "Stored event data",
        "metadata": "store-meta",
        "tags": { "source": "mcp-example" }
      }
    }
  }'
```

**Response:**

```json
{
  "content": [{ "type": "text", "text": "Event published successfully to events store channel 'example-events-store'" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; missing `channel`/`body` → `-32602`.

### events\_store\_read [#events_store_read]

Read stored events starting from a sequence number or a timestamp.

| Argument        | Type    | Required | Default | Description                                                                 |
| --------------- | ------- | -------- | ------- | --------------------------------------------------------------------------- |
| `channel`       | string  | Yes      | —       | Source events-store channel                                                 |
| `from_sequence` | integer | No       | —       | Start from this sequence number. Mutually exclusive with `from_time`        |
| `from_time`     | string  | No       | —       | Start from this ISO 8601 timestamp. Mutually exclusive with `from_sequence` |
| `max_messages`  | integer | Yes      | —       | Maximum number of messages to return (1–100)                                |

<Callout type="info">
  `from_sequence` and `from_time` are mutually exclusive — supply at most one.
</Callout>

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "max_messages"],
      "properties": {
        "channel": { "type": "string" },
        "from_sequence": { "type": "integer", "minimum": 1 },
        "from_time": { "type": "string", "format": "date-time" },
        "max_messages": { "type": "integer", "minimum": 1, "maximum": 100 }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "events_store_read",
      "arguments": { "channel": "example-events-store", "from_sequence": 1, "max_messages": 10 }
    }
  }'
```

**Response** — a JSON array of stored events, each with its `sequence` and `timestamp`:

```json
{
  "content": [{ "type": "text", "text": "[{\"body\":\"Stored event data\",\"metadata\":\"store-meta\",\"sequence\":1,\"timestamp\":\"2026-06-08T12:00:00Z\"}]" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; a non-existent channel returns an empty result; missing `channel` → `-32602`.

### events\_store\_read\_latest [#events_store_read_latest]

Read the N most recent stored events.

| Argument  | Type    | Required | Default | Description                            |
| --------- | ------- | -------- | ------- | -------------------------------------- |
| `channel` | string  | Yes      | —       | Source events-store channel            |
| `count`   | integer | No       | `1`     | Number of most recent events to return |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel"],
      "properties": {
        "channel": { "type": "string" },
        "count": { "type": "integer", "minimum": 1, "default": 1 }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "events_store_read_latest",
      "arguments": { "channel": "example-events-store", "count": 3 }
    }
  }'
```

**Response** — the most recent events, newest first:

```json
{
  "content": [{ "type": "text", "text": "[{\"body\":\"Stored event 3\",\"sequence\":3},{\"body\":\"Stored event 2\",\"sequence\":2},{\"body\":\"Stored event 1\",\"sequence\":1}]" }],
  "isError": false
}
```

**Errors:** reserved channel → `isError: true`; a non-existent channel returns an empty result; missing `channel` → `-32602`.

## Command & query tools [#command--query-tools]

Synchronous request/reply. See [Command & query tools](/aiway/mcp/tools/commands-queries) for language examples.

### command\_send [#command_send]

Send a command and wait for acknowledgment from a subscriber.

| Argument          | Type    | Required | Default | Description                                 |
| ----------------- | ------- | -------- | ------- | ------------------------------------------- |
| `channel`         | string  | Yes      | —       | Target command channel                      |
| `body`            | string  | Yes      | —       | Command body content                        |
| `timeout_seconds` | integer | No       | `10`    | Timeout in seconds waiting for the response |
| `metadata`        | string  | No       | `""`    | Optional command metadata string            |
| `tags`            | object  | No       | `{}`    | Key-value tags for command classification   |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "body"],
      "properties": {
        "channel": { "type": "string" },
        "body": { "type": "string" },
        "timeout_seconds": { "type": "integer", "minimum": 1, "default": 10 },
        "metadata": { "type": "string", "default": "" },
        "tags": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "command_send",
      "arguments": {
        "channel": "example-commands",
        "body": "do-work",
        "timeout_seconds": 10,
        "metadata": "cmd-meta",
        "tags": { "action": "process" }
      }
    }
  }'
```

**Response (success):**

```json
{
  "content": [{ "type": "text", "text": "Command executed successfully on channel 'example-commands'" }],
  "isError": false
}
```

**Errors:** reserved channel, no subscriber (timeout), or subscriber rejection → `isError: true`; missing `channel`/`body` → `-32602`.

### query\_send [#query_send]

Send a query and receive a data response from a subscriber.

| Argument          | Type    | Required | Default | Description                                 |
| ----------------- | ------- | -------- | ------- | ------------------------------------------- |
| `channel`         | string  | Yes      | —       | Target query channel                        |
| `body`            | string  | Yes      | —       | Query body content                          |
| `timeout_seconds` | integer | No       | `30`    | Timeout in seconds waiting for the response |
| `metadata`        | string  | No       | `""`    | Optional query metadata string              |
| `tags`            | object  | No       | `{}`    | Key-value tags for query classification     |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "body"],
      "properties": {
        "channel": { "type": "string" },
        "body": { "type": "string" },
        "timeout_seconds": { "type": "integer", "minimum": 1, "default": 30 },
        "metadata": { "type": "string", "default": "" },
        "tags": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "query_send",
      "arguments": {
        "channel": "example-queries",
        "body": "get-data",
        "timeout_seconds": 30,
        "metadata": "qry-meta",
        "tags": { "action": "lookup" }
      }
    }
  }'
```

**Response (success)** — the subscriber's reply payload as the text block:

```json
{
  "content": [{ "type": "text", "text": "{\"data\":\"query response payload from subscriber\"}" }],
  "isError": false
}
```

**Errors:** reserved channel, no subscriber (timeout), or subscriber rejection → `isError: true`; missing `channel`/`body` → `-32602`.

## Channel tools [#channel-tools]

Discovery and inspection of channels. See [Channel tools](/aiway/mcp/tools/channel-management) for language examples.

### channel\_list [#channel_list]

List channels, optionally filtered by type or name pattern. An empty list is a normal successful result.

| Argument  | Type   | Required | Default | Description                                                                        |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------- |
| `type`    | string | No       | —       | Filter by channel type (`queues`, `events`, `events_store`, `commands`, `queries`) |
| `pattern` | string | No       | —       | Filter by channel name pattern or prefix                                           |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": [],
      "properties": {
        "type": { "type": "string" },
        "pattern": { "type": "string" }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
      "name": "channel_list",
      "arguments": {}
    }
  }'
```

**Response** — a JSON array of channel descriptors:

```json
{
  "content": [{ "type": "text", "text": "[{\"name\":\"example-queue\",\"type\":\"queues\",\"is_active\":true},{\"name\":\"example-events\",\"type\":\"events\",\"is_active\":true}]" }],
  "isError": false
}
```

**Errors:** invalid arguments → `-32602`. No tool-specific failures otherwise.

### channel\_info [#channel_info]

Get metadata for a specific channel.

| Argument  | Type   | Required | Default | Description                                                              |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------------ |
| `channel` | string | Yes      | —       | Channel name                                                             |
| `type`    | string | Yes      | —       | Channel type (`queues`, `events`, `events_store`, `commands`, `queries`) |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["channel", "type"],
      "properties": {
        "channel": { "type": "string" },
        "type": { "type": "string" }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 12,
    "method": "tools/call",
    "params": {
      "name": "channel_info",
      "arguments": { "channel": "example-queue", "type": "queues" }
    }
  }'
```

**Response (success)** — channel metadata with traffic counters:

```json
{
  "content": [{ "type": "text", "text": "{\"name\":\"example-queue\",\"type\":\"queues\",\"is_active\":true,\"incoming\":5,\"outgoing\":3}" }],
  "isError": false
}
```

**Errors:** non-existent channel → `isError: true`.

## Agent-bridge tools [#agent-bridge-tools]

These 4 tools appear in `tools/list` **only when the A2A agent registry is present**. They turn an MCP client into an A2A caller. See [Agent-bridge tools](/aiway/mcp/tools/agent-bridge) for language examples and the [A2A connector](/aiway/a2a) for the agent model.

### agent\_list [#agent_list]

List registered agents, optionally filtered by skill tags. An empty list is a normal successful result.

| Argument     | Type            | Required | Default | Description                 |
| ------------ | --------------- | -------- | ------- | --------------------------- |
| `skill_tags` | array of string | No       | —       | Filter agents by skill tags |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": [],
      "properties": {
        "skill_tags": { "type": "array", "items": { "type": "string" } }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 13,
    "method": "tools/call",
    "params": {
      "name": "agent_list",
      "arguments": {}
    }
  }'
```

**Response** — a JSON array of agents with their skills:

```json
{
  "content": [{ "type": "text", "text": "[{\"agent_id\":\"echo-01\",\"name\":\"Echo Agent 01\",\"skills\":[{\"id\":\"echo\",\"name\":\"Echo\",\"tags\":[\"test\",\"echo\"]}]}]" }],
  "isError": false
}
```

**Errors:** invalid arguments → `-32602`. No tool-specific failures otherwise.

### agent\_info [#agent_info]

Get detailed metadata for a specific agent.

| Argument   | Type   | Required | Default | Description                 |
| ---------- | ------ | -------- | ------- | --------------------------- |
| `agent_id` | string | Yes      | —       | Agent identifier to look up |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["agent_id"],
      "properties": {
        "agent_id": { "type": "string" }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 14,
    "method": "tools/call",
    "params": {
      "name": "agent_info",
      "arguments": { "agent_id": "echo-01" }
    }
  }'
```

**Response (success)** — the agent's card, including its registered HTTP `url` and skills:

```json
{
  "content": [{ "type": "text", "text": "{\"agent_id\":\"echo-01\",\"name\":\"Echo Agent 01\",\"description\":\"echo agent\",\"version\":\"1.0.0\",\"url\":\"http://localhost:18080/\",\"skills\":[{\"id\":\"echo\",\"name\":\"Echo\",\"tags\":[\"test\",\"echo\"]}]}" }],
  "isError": false
}
```

**Errors:** non-existent agent → `isError: true`.

### agent\_send [#agent_send]

Send a message to an agent. The connector builds a `message/send` envelope and forwards it over the broker as a Query to `_AGENTS_.agents/<agent_id>`.

| Argument          | Type    | Required | Default | Description                                                       |
| ----------------- | ------- | -------- | ------- | ----------------------------------------------------------------- |
| `agent_id`        | string  | Yes      | —       | Target agent identifier                                           |
| `message`         | string  | Yes      | —       | Message content to send to the agent                              |
| `blocking`        | boolean | No       | `true`  | Wait for the agent response if `true`; fire-and-forget if `false` |
| `context_id`      | string  | No       | —       | Conversation context ID for multi-turn interactions               |
| `timeout_seconds` | integer | No       | —       | Timeout in seconds. The server adds a +10s `GatewayTimeoutBuffer` |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["agent_id", "message"],
      "properties": {
        "agent_id": { "type": "string" },
        "message": { "type": "string" },
        "blocking": { "type": "boolean", "default": true },
        "context_id": { "type": "string" },
        "timeout_seconds": { "type": "integer", "minimum": 1 }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 15,
    "method": "tools/call",
    "params": {
      "name": "agent_send",
      "arguments": { "agent_id": "echo-01", "message": "hello from MCP" }
    }
  }'
```

**Response (success)** — the agent's reply payload as the text block:

```json
{
  "content": [{ "type": "text", "text": "{\"echo\":{\"method\":\"message/send\",\"params\":{\"message\":\"hello from MCP\"}},\"received_headers\":{}}" }],
  "isError": false
}
```

**Errors:** non-existent agent or timeout exceeded → `isError: true`.

### agent\_query [#agent_query]

Query an agent with a specific JSON-RPC method.

| Argument   | Type   | Required | Default | Description                                                              |
| ---------- | ------ | -------- | ------- | ------------------------------------------------------------------------ |
| `agent_id` | string | Yes      | —       | Target agent identifier                                                  |
| `method`   | string | Yes      | —       | Query method to invoke (`tasks/get`, `tasks/cancel`, or a custom method) |
| `params`   | object | No       | —       | Method-specific parameters                                               |

<Accordions>
  <Accordion title="inputSchema (JSON Schema)">
    ```json
    {
      "type": "object",
      "required": ["agent_id", "method"],
      "properties": {
        "agent_id": { "type": "string" },
        "method": { "type": "string" },
        "params": { "type": "object" }
      }
    }
    ```
  </Accordion>
</Accordions>

```bash
curl -X POST http://localhost:9090/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 16,
    "method": "tools/call",
    "params": {
      "name": "agent_query",
      "arguments": { "agent_id": "echo-01", "method": "tasks/get" }
    }
  }'
```

**Response (success):**

```json
{
  "content": [{ "type": "text", "text": "{\"echo\":{\"method\":\"tasks/get\",\"params\":{}},\"received_headers\":{}}" }],
  "isError": false
}
```

**Errors:** non-existent agent or timeout exceeded → `isError: true`.

## Related [#related]

<Cards>
  <Card title="Tools overview" href="/aiway/mcp/tools" description="The 15-tool map and the tools/call response envelope." />

  <Card title="Endpoints" href="/aiway/mcp/reference/endpoints" description="POST /mcp, GET /mcp, and the JSON-RPC methods." />

  <Card title="Error codes" href="/aiway/mcp/reference/error-codes" description="JSON-RPC base codes, -32010 auth, and isError semantics." />

  <Card title="Channel resolution" href="/aiway/mcp/guides/channel-resolution" description="How tool channels map to KubeMQ and the reserved _AGENTS_. prefix." />
</Cards>