---
title: "Agent Inbox"
method: GET
path: "/agent/inbox"
---

# Agent Inbox

`GET /agent/inbox`

## Request

- Base URL: `https://api.local-mcp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.local-mcp.com/agent/inbox`
- Auth: none declared

Messages for this machine that this agent has not read yet.

lmcp-mac#543: with `peek=true` it is a read and nothing else. It serves what this reader
has not ACKNOWLEDGED (a delivered message comes back until `agent_ack` names it) and writes
nothing about the messages; the delivered mark is then written by the acknowledgement.
Without `peek` (every client up to 3.0.420, and a tray's background poll) nothing changes:
the same statements, and serving a message stamps it delivered, which is what keeps those
clients from getting it twice.

Reads are per agent, so a broadcast to the machine reaches every agent on it
instead of the first one to poll swallowing it.

Delivery is at-least-once, not exactly-once: the SELECT and the read-marking
INSERT are separate statements under READ COMMITTED, so two concurrent polls
by the same agent_id can both return the same message. Nothing is lost; a
message can repeat. Coordination messages are idempotent to act on (a second
`freeze` means what the first one meant), so this is left as is rather than
paying for SELECT ... FOR UPDATE SKIP LOCKED.

## Query parameters

- `agent_id` string, required: Who reads (an agent session)
- `limit` integer
- `background` boolean: true when the client's automatic consumer makes the call, not the agent: it does not count as activity and does not renew presence.
- `peek` boolean: true to read without marking: the messages this agent has not acknowledged are served and nothing is written about them; agent_ack then marks them delivered and acknowledged. Without it, serving a message marks it delivered.
- `wake_token` string, nullable: The token of an auto-wake prompt (MESH_WAKE_STATES only).

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/local-mcp/apis/lmcp-api.md) · [All operations](https://skmtc.dev/local-mcp/apis/lmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/local-mcp/apis/lmcp-api/revisions/f1f1c502623a?raw)