MCP server and agent API
Reference for the LastWorker MCP server (Model Context Protocol) and the REST agent API. Claude Code, Claude Desktop, Cursor or your own code can use them to work support tickets: read the threads waiting on a reply, then post a draft or send the reply. They cover email, web chat and SMS threads and phone calls. A phone call is read with its transcript and followed up by email or text in a new thread linked to the call.
The product overview is on the MCP server page.
What the MCP server and API do
The MCP server and the REST routes offer the same operations. They list the email, chat and SMS threads in your inbox, either the whole inbox or only the threads waiting on a reply, with each thread's ticket status. They return the full message history for any one thread. They post a reply to a thread, either as a draft or as a message sent straight to the customer on the thread's channel: email, web chat or SMS. A coding agent can use the MCP tools without any glue code.
Phone calls have their own list. Each call comes with its transcript, length, ticket status and transfer result. From a finished call, an agent can email or text the caller, which is the same action as Send a follow-up on an ended call in the inbox. An agent can also start a new email or text to any address or number, and set a ticket to resolved, in progress or escalated.
Every sent message carries a delivery status, which for a text follows the carrier's receipt. Every contact carries its opt-outs, and a new text or email to a contact who opted out of that channel is refused.
Create an API key
Open MCP in the dashboard and create a key there. Keys start with lw_live_ and are shown once. Send the key on every request as a bearer token:
Authorization: Bearer lw_live_...Each key is limited to 60 requests per minute across REST and MCP. On the REST routes, a key past that limit gets 429 with a Retry-After header that says how many seconds to wait. An invalid or revoked key gets 401 with the body { "error": "Invalid API key" }. A conversation id that is not in your account returns 404.
On the MCP server, initialize and tools/list answer with no key. A tool call with a missing, invalid, revoked or over-limit key returns a tool error saying the server needs a key. The wording is the same when the cause is the rate limit.
The reply setting and the draft-or-send rule
Step 3 on the MCP page in the dashboard, Choose what post_reply does, is an account setting with three values for replies posted through the post_reply MCP tool or POST /api/v1/conversations/:id/reply. Follow each channel's AI mode is the default. Always save as draft means every reply waits as a draft. Always send means every reply goes to the customer on any channel, and no channel's AI mode changes.
When an agent posts a reply, LastWorker decides between saving a draft and sending in this order. The first rule that matches wins.
| Order | Condition | Outcome |
|---|---|---|
| 1 | Request body has mode: "draft" | Saved as a draft. |
| 2 | Account setting is Always save as draft | Saved as a draft. |
| 3 | Account setting is Always send | Sent to the customer. Response says sent. |
| 4 | The thread's channel (email, web chat or SMS) has AI mode auto | Sent to the customer. Response says sent. |
| 4 | The thread's channel has AI mode review or manual | Saved as a draft. Response says drafted. |
A person sends a draft from the inbox, on email, web chat and SMS.
mode: "send" and leaving mode out behave the same: rules 2, 3 and 4 decide. mode: "send" cannot override Always save as draft or a channel on review or manual. In those cases the reply is saved as a draft and the response says drafted.
New channels start on manual, so post_reply drafts until you turn on Always send or change the mode. An older channel with no AI mode or approval setting stored resolves to auto, and so does a thread with no active channel of its type. post_reply sends in both cases. The get_account MCP tool and GET /api/v1/me return the resolved mode of each active channel.
A channel on auto or review also runs the built-in AI on inbound messages, billed at $0.04 per reply, plus $0.03 per segment when the reply goes out by SMS. post_reply itself does not charge the AI rate. To send with the built-in AI off, leave the channel on manual and turn on Always send.
REST reference
All routes are under https://lastworker.com. Requests and responses are JSON, except attachment downloads, which return the file.
GET /api/v1/me
Returns the account the key belongs to, the agent reply setting, and each agent with its active channels and their AI mode.
curl https://lastworker.com/api/v1/me \
-H "Authorization: Bearer lw_live_..."{
"account": {
"id": "6f1c2a0e-9b7d-4c1e-8a2b-0d3e4f5a6b7c",
"business_name": "Acme Plumbing",
"agent_reply_mode": "channel"
},
"agents": [
{
"id": "2b9e4d1a-7c3f-4e8b-9a1d-5f6e7a8b9c0d",
"name": "Support",
"channels": [
{ "type": "email", "ai_mode": "review" }
]
}
]
}agent_reply_mode is channel (Follow each channel's AI mode), draft (Always save as draft) or send (Always send). ai_mode is one of auto, review or manual.
GET /api/v1/conversations
Lists email, web chat and SMS threads, newest first. Query parameters:
needs_reply=truereturns only threads whose newest message is from the customer, with no pending draft after it, and whose ticket is open, in progress, awaiting review, escalated or awaiting customer. System notes such as the escalation notice, and the tool call rows an escalation leaves behind, are skipped when deciding which message is newest. Without it, threads the AI has already answered are included.tabapplies an inbox tab:attention(escalated, awaiting review, missed),active,all,resolved,notificationsorspam. Without it, spam and notification mail are left out and every other status is included.agent_idlimits the list to one agent.limitis the page size. Default 20, maximum 100.beforeis an ISO timestamp cursor overlast_message_at. The response includesnext_beforewhen there are more threads. Pass it back asbeforeto get the next page. It isnullon the last page.sinceis an ISO timestamp. It keeps threads whose newest message is at or after it, so a poller can pass the time of its last run.
curl "https://lastworker.com/api/v1/conversations?needs_reply=true&limit=20" \
-H "Authorization: Bearer lw_live_..."{
"conversations": [
{
"id": "a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f",
"agent": { "id": "2b9e4d1a-7c3f-4e8b-9a1d-5f6e7a8b9c0d", "name": "Support" },
"channel_type": "email",
"subject": "Invoice 1042 shows the wrong address",
"ticket": { "id": "c1e3a5b7-9d2f-4b6a-8c0e-1f3a5b7c9d2e", "status": "open", "priority": "normal" },
"contact": {
"id": "d4b6a8c0-2e1f-4c3a-9b5d-7f9e1a3c5b7d",
"name": "Dana Ortiz",
"email": "[email protected]",
"phone": null,
"opted_out": { "sms": false, "email": false }
},
"last_message_at": "2026-10-13T14:02:11.000Z",
"last_customer_message": {
"id": "e5c7b9d1-3f2a-4d4b-8e6f-9a1c3e5b7d9f",
"content": "The invoice you sent still has our old address.",
"created_at": "2026-10-13T14:02:11.000Z"
},
"has_pending_draft": false,
"needs_reply": true
}
],
"next_before": "2026-10-13T14:02:11.000Z"
}GET /api/v1/conversations/:id
Returns one thread. The response has every field from the list item, plus summary and messages. Messages are in chronological order.
curl https://lastworker.com/api/v1/conversations/a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f \
-H "Authorization: Bearer lw_live_..."{
"id": "a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f",
"agent": { "id": "2b9e4d1a-7c3f-4e8b-9a1d-5f6e7a8b9c0d", "name": "Support" },
"channel_type": "email",
"subject": "Invoice 1042 shows the wrong address",
"ticket": { "id": "c1e3a5b7-9d2f-4b6a-8c0e-1f3a5b7c9d2e", "status": "open", "priority": "normal" },
"contact": { "id": "d4b6a8c0-2e1f-4c3a-9b5d-7f9e1a3c5b7d", "name": "Dana Ortiz", "email": "[email protected]", "phone": null, "opted_out": { "sms": false, "email": false } },
"last_message_at": "2026-10-13T14:02:11.000Z",
"last_customer_message": { "id": "e5c7b9d1-3f2a-4d4b-8e6f-9a1c3e5b7d9f", "content": "...", "created_at": "2026-10-13T14:02:11.000Z" },
"has_pending_draft": false,
"needs_reply": true,
"summary": "Customer wants invoice 1042 reissued with the new address.",
"messages": [
{
"id": "7c2e9a4f-6d1b-4f3a-b8e5-1a9c3d5f7b2e",
"role": "user",
"authored_by": "customer",
"content": "Hi, invoice 1042 has our old address on it.",
"created_at": "2026-10-12T09:30:00.000Z",
"type": null,
"is_draft": false,
"cc": [],
"attachments": [
{
"filename": "invoice-1042.pdf",
"content_type": "application/pdf",
"size": 48213,
"url": "https://lastworker.com/api/v1/attachments/email-attachments/2026-10-12/4f1c9e2a-7b3d-4a8e-9c6f-2d1e8b5a7c3f/0-invoice-1042.pdf"
}
],
"delivery": null
},
{
"id": "9f4b1d6e-2a8c-4b7d-a3f1-6e8c0a2d4f6b",
"role": "agent",
"authored_by": "human_agent",
"content": "Sorry about that. What should the address read?",
"created_at": "2026-10-12T10:05:40.000Z",
"is_draft": false,
"cc": ["[email protected]"],
"attachments": [],
"delivery": { "status": "accepted", "updated_at": null, "error": null }
},
{
"id": "e5c7b9d1-3f2a-4d4b-8e6f-9a1c3e5b7d9f",
"role": "user",
"authored_by": "customer",
"content": "The invoice you sent still has our old address.",
"created_at": "2026-10-13T14:02:11.000Z",
"is_draft": false,
"cc": [],
"attachments": [],
"delivery": null
}
]
}Every row in the thread comes back, including system notes, tool rows and pending drafts, which have is_draft set to true. role is user, agent, system, tool_call or tool_result. authored_by is customer, ai, human_agent, system or null. Bcc addresses are not returned. Phone calls store their tool rows too, so a call's thread shows each action the AI ran and what it returned. type names what a system note records, such as escalation_outcome (which rule ran and who was notified, or that nobody was) or transfer_skipped. It is null on other rows.
attachments lists the files on each message: files a customer emailed or uploaded in chat, files sent from the inbox, and voicemail recordings. Each has filename, content_type, size in bytes and url. content_type and size are null when they were not recorded. A message with no files has an empty list.
delivery is set on a message that was sent by email or text, and is null on everything else. See Delivery status. contact.opted_out says which channels the contact asked not to be contacted on. See Contact opt-outs.
GET /api/v1/attachments/:key
Downloads one attachment. Use the url from a message's attachments as it is, with the same bearer key. The response is the file itself with its Content-Type. Images, audio, video, PDF and plain text are served inline. Every other type is served with Content-Disposition: attachment.
curl -o invoice-1042.pdf \
"https://lastworker.com/api/v1/attachments/email-attachments/2026-10-12/4f1c9e2a-7b3d-4a8e-9c6f-2d1e8b5a7c3f/0-invoice-1042.pdf" \
-H "Authorization: Bearer lw_live_..."A key reads only files on messages in its own account's conversations. A file in another account returns 404, the same as a file that does not exist. A storage error returns 502. Downloads count toward the same rate limit as other requests.
POST /api/v1/conversations/:id/reply
Posts a reply to the thread. content is required, plain text, up to 20000 characters. Line breaks are kept. mode is optional and is either draft or send. The draft-or-send rule decides what happens with each value. A reply has no attachments and cannot set Cc. An email send copies whoever the customer copied on their last message.
curl -X POST https://lastworker.com/api/v1/conversations/a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f/reply \
-H "Authorization: Bearer lw_live_..." \
-H "Content-Type: application/json" \
-d '{
"content": "Thanks Dana. I have reissued invoice 1042 with the new address.",
"mode": "draft"
}'One of two success responses comes back:
{ "result": "drafted", "message_id": "b8d0f2a4-6c1e-4a9b-8d3f-5a7c9e1b3d5f" }{ "result": "sent", "message_id": "3a5c7e9b-1d4f-4c8a-9e2b-7d9f1b3c5a8e", "method": "email" }method is email or sms for those channels. On web chat it is relay when the visitor was online, email when they were offline and have an address, or stored when the message waits in the thread for their return. An SMS send is billed at $0.03 per segment. Drafts, email sends and web chat sends are free.
A draft moves the ticket to awaiting_review, unless the ticket is escalated, which stays escalated. A new draft replaces the earlier pending one. A send moves the ticket to awaiting_customer from any status, including escalated and resolved.
A ticket is resolved with POST /api/v1/conversations/:id/status, or by a person in the dashboard. Auto-resolve also does it once the ticket is in awaiting_customer, your reply is the last message, and that message is older than the account's window, 48 hours by default. Auto-resolve is on by default and set per account.
Errors return a JSON body with an error field and one of these statuses:
- 400: the body is invalid or
contentis empty, the thread is a phone call (use the follow-up route), an email thread's contact has no email address, an SMS thread's contact has no phone number, or the agent has no active SMS number. - 402: the balance does not cover an SMS send. This check does not trigger auto-reload.
- 404: the conversation is not in your account.
- 409: the SMS registration for the number is not active.
- 502: the email or SMS provider rejected the send, including the email fallback on web chat.
A missing address or number, a 402, a 409 and a 502 all leave the message row in the thread, so the inbox shows what was attempted. The ticket does not change. The row counts as an agent reply, so needs_reply turns false and the thread leaves the needs-reply list although the customer received nothing. Check the result of each send.
POST /api/v1/conversations/:id/status
Sets the ticket status of a thread or a phone call. status is resolved, in_progress or escalated. resolved closes the ticket, for example a call that needs no follow-up. in_progress reopens it. escalated moves it to Needs Attention in the inbox.
curl -X POST https://lastworker.com/api/v1/conversations/a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f/status \
-H "Authorization: Bearer lw_live_..." \
-H "Content-Type: application/json" \
-d '{ "status": "resolved" }'{ "result": "updated", "conversation_id": "a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f", "status": "resolved" }An id that is not in your account returns 404. Any other status value returns 400.
Phone calls and follow-ups
A phone call is a conversation with channel_type phone. Calls are listed and read on their own routes. A finished call has no line left to reply on, so a follow-up goes out by email or text and opens a new thread linked to the call.
GET /api/v1/calls
Lists phone calls, newest first by start time. Query parameters:
statuskeeps calls whose ticket has that status:open,in_progress,awaiting_customer,awaiting_review,escalated,resolved,closedormissed. A call that was answered ends asresolved. A call nobody answered ends asmissed. A call with a voicemail, or one that was escalated during the call, ends asescalated.ended=truereturns finished calls only.ended=falsereturns calls still in progress.sinceis an ISO timestamp. It keeps calls that ended at or after it, so a poller can pass the time of its last run.agent_idlimits the list to one agent.limitis the page size. Default 20, maximum 100.beforeis an ISO timestamp cursor overstarted_at. Pass backnext_beforeto get the next page. It isnullon the last page.
curl "https://lastworker.com/api/v1/calls?ended=true&since=2026-11-15T00:00:00Z" \
-H "Authorization: Bearer lw_live_..."{
"calls": [
{
"id": "5b7d9f1a-3c2e-4b6d-8f0a-1c3e5a7b9d2f",
"agent": { "id": "2b9e4d1a-7c3f-4e8b-9a1d-5f6e7a8b9c0d", "name": "Support" },
"ticket": { "id": "8e0a2c4f-6b1d-4e3a-9c5f-7a9b1d3e5c7a", "status": "escalated", "priority": "normal" },
"contact": {
"id": "d4b6a8c0-2e1f-4c3a-9b5d-7f9e1a3c5b7d",
"name": "Dana Ortiz",
"email": "[email protected]",
"phone": "+15557654321",
"opted_out": { "sms": false, "email": false }
},
"from": "+15557654321",
"to": "+15550001111",
"started_at": "2026-11-15T15:00:00.000Z",
"ended_at": "2026-11-15T15:02:05.000Z",
"duration_seconds": 125,
"summary": "Asked whether leaf cleanup can be repeated this year.",
"transfer": { "stage": "failed", "outcome": "no_answer" },
"voicemail": false,
"follow_ups": []
}
],
"next_before": null
}from is the caller's number and to is the number they dialled. ended_at and duration_seconds are null while the call is in progress. summary is null when none was written.
transfer is null unless a live transfer to a person was tried or skipped. Its outcome is connected, no_answer, caller_left, human_took_over or ended_by_team, and null while the transfer is still going. A skipped transfer has stage skipped and the reason as its outcome: caller_is_transfer_number, balance_too_low, transfer_limit, phone_not_set_up, own_number or no_country_code. voicemail is true when the caller left a recording. follow_ups lists the email and SMS threads opened from the call, each with via, conversation_id and sent_at.
GET /api/v1/calls/:id
Returns one call. The response has every field from the list item, plus messages, follow_up_options and related_conversations. An id that is not a phone call in your account returns 404.
{
"id": "5b7d9f1a-3c2e-4b6d-8f0a-1c3e5a7b9d2f",
"...": "every field from the list item",
"messages": [
{
"id": "1d3f5b7a-9c2e-4a6b-8d0f-3e5c7a9b1d2f",
"role": "user",
"authored_by": "customer",
"content": "Can you do the leaf cleanup again this year?",
"created_at": "2026-11-15T15:00:05.000Z",
"is_draft": false,
"cc": [],
"attachments": [],
"delivery": null
}
],
"follow_up_options": {
"email": { "available": true, "to": "[email protected]", "subject": "Following up on your call with Support", "opted_out": false },
"sms": { "available": true, "to": "+15557654321", "opted_out": false }
},
"related_conversations": [
{
"id": "a3d5f7b9-1c2e-4a6b-8d0f-2e4c6a8b0d1f",
"channel_type": "email",
"subject": "Invoice 1042 shows the wrong address",
"ticket_status": "resolved",
"last_message_at": "2026-10-13T14:02:11.000Z"
}
]
}messages is the transcript, in the same shape as GET /api/v1/conversations/:id. A voicemail recording is an attachment on its message. follow_up_options says, for email and for SMS, whether a follow-up can be sent and where it would go. Email is available when the agent has an active email channel, and to is the address on the caller's contact or null. SMS is available when the agent has a number that can text and the caller's number is known. A channel the caller opted out of has opted_out true and is not available. related_conversations lists the caller's other threads, newest first, up to 20.
POST /api/v1/calls/:id/follow-up
Emails or texts the caller after a finished call. It is the same action as Send a follow-up on an ended call in the inbox. It opens a new email or SMS thread, stores the call's id on that thread, leaves a note on the call that points to it, and resolves the call's ticket. The customer's answer arrives in the new thread, where post_reply works as on any other thread.
viais required:emailorsms.bodyis required, plain text, up to 20000 characters.toapplies to email. Left out, the email goes to the address on the caller's contact. An address you pass is saved on that contact. A text always goes to the caller's number.subjectapplies to email. Left out, it isFollowing up on your call withand the agent's name.idempotency_keyis optional, up to 200 characters. TheIdempotency-Keyheader is read when the body has none. See Idempotency keys.
curl -X POST https://lastworker.com/api/v1/calls/5b7d9f1a-3c2e-4b6d-8f0a-1c3e5a7b9d2f/follow-up \
-H "Authorization: Bearer lw_live_..." \
-H "Content-Type: application/json" \
-d '{
"via": "sms",
"body": "Thanks for calling. We can do the leaf cleanup on Friday morning.",
"idempotency_key": "call-5b7d9f1a-follow-up-1"
}'{
"result": "sent",
"via": "sms",
"to": "+15557654321",
"conversation_id": "f2a4c6e8-0b1d-4f3a-8c5e-7a9c1e3b5d7f",
"message_id": "6c8e0a2d-4f1b-4a3c-9e5d-7b9d1f3a5c8e",
"ticket_id": "0a2c4e6f-8b1d-4c3e-9a5f-7c9e1b3d5f7a",
"call_id": "5b7d9f1a-3c2e-4b6d-8f0a-1c3e5a7b9d2f",
"provider_message_id": "40319a2b-6c1d-4e7f-8a9b-0c1d2e3f4a5b",
"replayed": false
}result sent means the email or SMS provider accepted the message. provider_message_id is the provider's id for it, or null when none came back. conversation_id, message_id and ticket_id belong to the new thread. A text is sent from the agent's SMS number, or from the number the caller dialled when the agent has no separate SMS channel, and is billed at $0.03 per segment. An email is free. To learn whether a text reached the phone, read the message's delivery on the new thread, as described under Delivery status.
This route sends at once and has no draft form, so it follows the draft-or-send rule without the draft. It sends when the account setting is Always send. It also sends when the setting is Follow each channel's AI mode and the agent's email or SMS channel is on auto. In every other case it returns 409, sends nothing and leaves the call as it was. The error names the setting that stopped it.
Errors return a JSON body with an error field and one of these statuses:
- 400: the body is invalid, the agent has no active email channel or no number that can text, the caller's number is unknown, or an email was asked for with no address on the contact and none passed.
- 402: the balance does not cover the text. Auto-reload runs first when it is on, so this means the reload did not cover it either.
- 404: the id is not a phone call in your account.
- 409: the call has not ended, the account or channel setting does not allow a send, the contact has opted out of that channel, the SMS registration for the number is not active, or the idempotency key cannot be used.
- 502: the email or SMS provider refused the send. The new thread is removed and the call's ticket does not change.
POST /api/v1/messages
Starts a new email or SMS thread that is not tied to a call or to an existing thread. To answer an existing thread, use the reply route.
agent_idis required. The message goes out from that agent's email channel or SMS number.channelis required:emailorsms.tois required: an email address, or a phone number in international format such as+15551234567.subjectis required for an email.bodyis required, plain text, up to 20000 characters.to_nameis optional. It is saved on the contact when the contact has no name yet.idempotency_keyis optional and works as on the follow-up route.
curl -X POST https://lastworker.com/api/v1/messages \
-H "Authorization: Bearer lw_live_..." \
-H "Content-Type: application/json" \
-d '{
"agent_id": "2b9e4d1a-7c3f-4e8b-9a1d-5f6e7a8b9c0d",
"channel": "email",
"to": "[email protected]",
"subject": "Your spring estimate",
"body": "Here is the estimate we discussed."
}'The response has the same fields as the follow-up route without call_id. The new thread's ticket starts in awaiting_customer. The same send rule and the same error statuses apply. An agent_id that is not in your account returns 404.
Idempotency keys
The follow-up route and the new message route send something a customer receives, so a retry after a timeout could send it twice. Pass an idempotency_key of your own choosing with the request, and use the same key for every retry of that one send. Keys are kept per account.
- A retry with the same key and the same request returns the first response with
replayedset to true. Nothing is sent again. - The same key with a different request returns 409.
- A 502 is stored and replayed too, since the provider may have taken the message before it failed. Check the call's
follow_ups, then retry with a new key if it did not go out. - A request refused before anything was sent (400, 402, 404 or 409) does not use up the key. Fix the cause and send it again with the same key.
- While the first request is still running, or if it never finished, a retry returns 409 and sends nothing. Read the call's
follow_ups, or the conversation list, to see whether it went out before trying again with a new key.
Delivery status
Each message in GET /api/v1/conversations/:id and GET /api/v1/calls/:id has a delivery field. It is an object on a message that was sent by email or text, and null on customer messages, drafts, system notes and messages that went to the chat widget.
"delivery": {
"status": "failed",
"updated_at": "2026-11-15T15:10:04Z",
"error": { "code": "40300", "title": "Blocked due to STOP message", "detail": null }
}accepted: the email or SMS provider took the message. An email stays here.sent: the carrier has the text and has not reported back yet.delivered: the carrier confirmed the text reached the phone.failed: the text did not go out or was not delivered.errorhas the carrier's code, title and detail.unconfirmed: the carrier sent the text and got no confirmation back.
delivered, failed and unconfirmed are final. updated_at is the carrier's time for the latest status, and null while the status is accepted. A receipt usually arrives within seconds of the send, so read the thread again after a short wait. The send response itself reports only that the provider accepted the message.
Contact opt-outs
Every contact object has opted_out: { sms, email }. A contact who has opted out of a channel is not sent a new text or a new email on it. That covers a follow-up from a call and a new message, through this API and from the inbox. Those sends return 409 and nothing goes out. A reply on a thread the contact wrote on still goes out.
- A contact who texts
STOP,UNSUBSCRIBE,CANCEL,ENDorQUITas the whole message is opted out of texts at once. The carrier blocks further texts to that number as well. - A contact who texts
START,YESorSUBSCRIBEafter opting out is opted back in. - A person can set or clear Do not text and Do not email on the contact under Contacts in the dashboard.
- An agent can record an opt-out with the route below. Opting a contact back in is left to a person in the dashboard or to the contact.
POST /api/v1/contacts/:id/opt-out
Records that a contact asked not to be contacted on a channel, for example a caller who said so on a call. channel is sms or email. The contact id comes from the contact object on a call or a conversation.
curl -X POST https://lastworker.com/api/v1/contacts/d4b6a8c0-2e1f-4c3a-9b5d-7f9e1a3c5b7d/opt-out \
-H "Authorization: Bearer lw_live_..." \
-H "Content-Type: application/json" \
-d '{ "channel": "sms" }'{
"result": "updated",
"contact_id": "d4b6a8c0-2e1f-4c3a-9b5d-7f9e1a3c5b7d",
"opted_out": { "sms": true, "email": false }
}A contact id that is not in your account returns 404.
MCP setup
The MCP server is streamable HTTP at https://lastworker.com/api/mcp. It takes the same bearer key as a header. It exposes twelve tools:
get_account, the same response as/api/v1/me.list_conversations({ tab?, agent_id?, limit?, before?, since? }), every thread in the inbox, including ones the AI already answered. Same asGET /api/v1/conversationswithoutneeds_reply.list_conversations_needing_reply({ tab?, agent_id?, limit?, before?, since? }), only the threads waiting on a person. Same asneeds_reply=true.get_conversation({ id }), the same response asGET /api/v1/conversations/:id, including each message's attachments.get_attachment({ url }), reads one attachment by theurlfromget_conversation. Text files such as CSV, plain text and JSON up to 256 KB come back as text. PNG, JPEG, GIF and WebP images up to 5 MB come back as image content. Any other file, or a larger one, comes back as its filename, type, size and download URL, which you fetch fromGET /api/v1/attachments/:key.post_reply({ id, content, mode? }), the same rules and results asPOST /api/v1/conversations/:id/reply.list_calls({ status?, ended?, agent_id?, since?, before?, limit? }), the same response asGET /api/v1/calls.endedis a boolean here.get_call({ id }), the same response asGET /api/v1/calls/:id.send_call_follow_up({ id, via, body, to?, subject?, idempotency_key? }), the same rules and results asPOST /api/v1/calls/:id/follow-up.send_message({ agent_id, channel, to, body, subject?, to_name?, idempotency_key? }), the same rules and results asPOST /api/v1/messages.set_ticket_status({ id, status }), the same asPOST /api/v1/conversations/:id/status.opt_out_contact({ contact_id, channel }), the same asPOST /api/v1/contacts/:id/opt-out.
A failed tool call comes back as a result with isError set. A failure from post_reply, send_call_follow_up, send_message, set_ticket_status or opt_out_contact carries the same { "error": "..." } body as REST, without the status code.
Claude Code
Run this once in a terminal:
claude mcp add --transport http lastworker https://lastworker.com/api/mcp \
--header "Authorization: Bearer lw_live_..."Claude Desktop and Cursor
In Claude Desktop, add a custom connector under Customize > Connectors. Enter https://lastworker.com/api/mcp as the URL and choose No sign-in. Under Request headers, add authorization with the value Bearer lw_live_.... On Team and Enterprise plans an Owner adds the connector. Free Claude accounts are limited to one custom connector.
In Cursor, add this to .cursor/mcp.json:
{
"mcpServers": {
"lastworker": {
"url": "https://lastworker.com/api/mcp",
"headers": {
"Authorization": "Bearer lw_live_..."
}
}
}
}Support inbox skill
The support inbox skill is a Claude Code skill that works the inbox end to end. It pulls the queue and a seven day sweep of every thread, reads each one, looks the customer up in your own systems, writes a reply and posts it as a draft with post_reply. A person reviews each draft in the inbox and sends it. Sections 2 and 3 have fill-in blocks for your own lookups and the checks for each kind of issue. Those are the parts to edit; the rest works as is.
Save the skill as .claude/skills/support-inbox/SKILL.md in the repo you run Claude Code from, or as ~/.claude/skills/support-inbox/SKILL.md to have it everywhere, then run /support-inbox. Add the LastWorker MCP server first, as described in MCP setup. Download the file, or copy it from this page.
---
name: support-inbox
description: Work the LastWorker support inbox. Pull the email, web chat and SMS threads that need a reply, look each customer up in your own systems, and post an accurate reply. Use when asked to "do the inbox", "draft support replies", or when /support-inbox is invoked.
---
# Support inbox
Goal: every thread in the LastWorker inbox that is waiting on a person gets a reply grounded in
your own data, not in the customer's description of the problem.
Replies are posted with `mode: "draft"` unless the account owner has said otherwise. A draft sits
in the LastWorker inbox until a person reads it and presses Send. Nothing reaches a customer
without that step. Only read from your own systems while working this skill. Do not write to them.
## Setup, once
Create an API key at https://lastworker.com/dashboard/mcp and add the server:
```bash
claude mcp add --transport http lastworker https://lastworker.com/api/mcp \
--header "Authorization: Bearer lw_live_..."
```
Cursor takes the same URL and header in .cursor/mcp.json. Claude Desktop takes them as a custom
connector with No sign-in and a Request headers entry. Every call below is a LastWorker MCP tool. The same data is available over REST at
https://lastworker.com/docs/agents if you prefer curl.
## 1. Get the threads
Call `get_account` first. It lists your agents, each channel's AI mode (auto, review, manual) and
the account's reply setting, which decides whether `post_reply` sends or drafts.
Then pull two lists:
- `list_conversations_needing_reply({ tab: "attention", limit: 100 })`. This is the queue: threads
whose newest customer-or-agent message is from the customer, with no draft pending, restricted to
the inbox's Needs Attention tab (escalated, awaiting review, missed). Spam and notification mail
are already out. Follow `next_before` until it is null.
- `list_conversations({ tab: "all", limit: 100 })`. Every thread in the inbox, including the ones
the AI already answered. Page back 7 days with `next_before`.
Work every item in the queue whose `needs_reply` is true and `has_pending_draft` is false. Then go
through the 7-day sweep and also open any thread that matches one of these:
- A chat where only the AI answered. The AI's reply clears `needs_reply`, so a customer who keeps
asking after "the team is looking into it" never reaches the queue. Work any thread where a
customer message has no human reply after it.
- A thread with a pending draft where the customer wrote again after the draft. Re-check and post a
new draft, which replaces the old one.
One customer often has a chat and an email thread open at the same time. Search the sweep for the
contact email and read every thread for that customer before writing, so the reply answers their
latest message wherever it arrived.
Each item carries `agent.name`. If you run more than one product through LastWorker, use it to
tell which product the thread belongs to.
If the person gave you one thread id or pasted a conversation, work only that one.
Read the whole thread with `get_conversation({ id })`, not just the last message. Earlier turns
often hold the order number, the amount or the screenshot description that explains the latest one.
Each message lists its `attachments`. Open every one with `get_attachment({ url })` before you
write: customers send the screenshot or the spreadsheet that the question is about.
## 2. Identify the customer
The `contact.email` on the thread is the account email in most cases. Confirm it resolves to one
record in your system before you investigate. If it does not, try the phone number or the name
from the thread. If there is still no match, draft a short reply asking which email the account is
under, and say in the report that the lookup failed.
Fill in how a lookup works for your product:
```
Lookup by email: <command, SQL, or API call>
Lookup by phone: <command, SQL, or API call>
What it returns: <the fields you care about: plan, status, created date, last activity>
```
## 3. Classify and investigate
Pick one bucket, then run that bucket's checks. Write down what you found with dates and amounts.
The reply must rest on evidence.
Fill in your buckets. Three to eight is typical. For each one, name the data source and the exact
query or screen, so the agent does the same checks every time:
```
Billing: "I paid but nothing changed"
Source: <billing provider, e.g. Stripe customer search by email, then charges and subscriptions>
Also: <your own ledger table or page>
Known: <anything that commonly explains this, e.g. a card declined on retry>
Access: cannot log in, verification code never arrives
Source: <auth logs, analytics events for the email in the last 7 days>
Known: <recent outages or provider changes before blaming the customer>
Feature not working: <name the feature>
Source: <the table, log or admin page that shows what the customer actually did>
Known: <limits, unsupported cases, common misconfigurations>
Data import or migration
Source: <import jobs table, error logs>
Known: <what can and cannot be moved, and how long it takes>
Refund request
Policy: <your refund policy in one line. The agent repeats it and does not negotiate>
Abuse or fraud signal
Do not draft a reply. Put the evidence in the report for a person to decide.
```
Add product rules the agent must not get wrong. Examples: a price that is published versus one that
is internal, a limit per plan, a promise support is not allowed to make.
## 4. Write the reply
Sign as a named person on your team. Plain sentences, warm, specific. Say what you checked and what
you found, in the customer's terms (dates, amounts, the thing they clicked). Give the next step they
can take. No bulk apologies, no filler, no "I understand your frustration".
Do not quote internal table names, ids, vendor names or internal counts. Use them to decide what is
true, then state the fact without the number. Do not promise a refund, a date or a change on your
side unless a person has already done it.
Shape:
```
Hi <first name, or nothing>,
<what you found, one short paragraph>
<what happens next or what they can do, one short paragraph>
<name>
<product> Support
```
Plain text. Blank lines between paragraphs. No markdown. No bullet lists unless there are three or
more parallel steps.
If the evidence does not support an answer, write the honest version: what you checked, what you
could not confirm, and one question that would unblock it.
## 5. Post the reply
```
post_reply({ id: "<conversation id>", content: "<reply text>", mode: "draft" })
```
Expect `{ "result": "drafted" }`. Leave `mode` out only if the account owner has told you to send.
The account's reply setting and the channel's AI mode then decide, and the result says `sent` or
`drafted`.
## 6. Report
Finish with one table, one row per thread: customer email, bucket, the evidence in one line, and
whether a draft was posted or why not. Put any thread you were unsure about, and any abuse case, at
the top.
To have the skill send instead of draft, turn on Always send or set the channel to auto, and tell the skill to leave mode out. The account setting Always save as draft overrides that for every key.