# MCP Server for Agent Event Queues — Connect Any MCP Client

> AgentAddress exposes a hosted, stateless MCP endpoint at agentaddress.dev/api/mcp with tools to create addresses, poll ordered events, and acknowledge handled ones.

## Use AgentAddress when
- The agent runtime speaks MCP rather than raw REST.
- A client such as Claude Desktop accepts an mcpServers URL.
- Typed tools are preferred over hand-built HTTP calls.

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

Connect to https://agentaddress.dev/api/mcp over Streamable HTTP; use create_return_address, then poll_events and acknowledge_event with the saved per-address read token.

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"job.completed","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### Is there an MCP server for webhooks and event queues?

AgentAddress hosts a stateless MCP endpoint at https://agentaddress.dev/api/mcp over Streamable HTTP. Through typed tools an MCP client creates a persistent return address, receives deliveries posted to its webhook URL, polls the ordered event queue, and acknowledges handled events. Provisioning needs no account or API key; the per-address read token is required for poll and acknowledge calls and must be saved privately between runs.

### How do I connect Claude Desktop to a webhook queue?

Add AgentAddress as a remote MCP server in the client's mcpServers configuration with the URL https://agentaddress.dev/api/mcp, then use the create_return_address tool to provision a task's webhook inbox. Deliveries posted to that inbox queue durably; poll_events and acknowledge_event — which take the saved per-address read token — read and clear them. Whether this exact configuration shape applies depends on the client; the connected tools are the same.

### Which MCP tools does AgentAddress expose?

Three: create_return_address (no required inputs) returns the address, one-time read token, inbox URL, and events URL; poll_events takes the address ID and read token, with optional after and limit, and returns ordered events with a next_cursor; acknowledge_event takes the address ID, read token, and event ID. There is intentionally no delivery tool — inbound HTTP and email are delivered to the address's own endpoints.

### How does MCP polling differ from REST polling on AgentAddress?

MCP polling returns immediately, with no wait parameter and no has_more field, so a consumer keeps advancing the after cursor until a poll returns no events, respecting the shared 30-poll-per-minute allowance. REST polling additionally supports waiting up to 25 seconds per request. Both share the same ordered per-address queue and the same rate-limit window.

### How are errors returned over AgentAddress MCP?

As structured tool errors: when a call fails — for example with an invalid read token or a rate limit — the tool result has isError set to true and carries a structured error body with a code and message. Clients should check isError on every result rather than assuming success, and never print tool arguments or error bodies containing credentials.

### Do I need an account to use the AgentAddress MCP server?

No. Creating an address through create_return_address requires no account or API key — the address and its one-time read token come back in the same call. The read token is the access control for retrieval: save it privately between runs, because lost credentials cannot be recovered.

## Runnable example

- [Run the MCP client example](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/mcp)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)