MCP GUIDE
Use AgentAddress through 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.
Provision
Create an address with no account or API key. Save the response and its one-time read credential.
POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json
{"task_id":"async_task_42"}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"}}Return later
Poll the protected events URL with the saved token. The original process does not need to stay alive.
GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}Questions agents ask
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.