sdesk-mcp

Exposes your SDesk helpdesk to Claude as MCP tools, so Claude can triage tickets and send real replies to customers.

Why it works this way

SDesk tickets are Shopify support_ticket metaobjects with PUBLIC_READ_WRITE admin access, so anything holding a Shopify Admin token can already read them. Sending is different: agent replies go out through Amazon SES from SDesk's own backend, which then stamps ses_message_id onto the message.

Writing a message straight into the metaobject shows a reply in the SDesk UI that the customer never receives. This server therefore never touches Shopify directly. It calls POST /api/agent in the SDesk app, which calls the same sendReply() the inbox UI uses. One send path, one source of truth.

Setup

1. Set the API key on Vercel

The /api/agent route is disabled unless AGENT_API_KEY is set. Generate a fresh secret — do not reuse ADMIN_API_KEY, so this one can be revoked on its own:

openssl rand -hex 32

Add it in the SDesk Vercel project under Settings → Environment Variables as AGENT_API_KEY (Production), then redeploy so the route picks it up.

2. Install

cd sdesk-mcp
npm install

3. Register the server with Claude

claude mcp add sdesk \
  --env SDESK_BASE_URL=https://your-sdesk-domain \
  --env SDESK_API_KEY=<the key from step 1> \
  --env SDESK_SHOP=6b08f2.myshopify.com \
  -- node /absolute/path/to/sdesk-mcp/index.js

4. Check it

curl -s -X POST https://your-sdesk-domain/api/agent \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shop":"6b08f2.myshopify.com","action":"list_tickets","status":"open","limit":5}'

A 401 means the key is wrong or not deployed. A 404 with "No installed session found" means the shop domain is wrong or the app is not installed on it.

Tools

| Tool | Sends email? | What it does | |---|---|---| | sdesk_list_tickets | no | Triage the inbox; filter by status, channel, customer, return | | sdesk_get_ticket | no | Full thread, notes, activity log, and duplicate siblings | | sdesk_reply | yes | Real SES reply to the customer, then sets status to pending | | sdesk_add_note | no | Internal note — good for staging a draft for human review | | sdesk_update_status | no | Change ticket status |

The duplicate-ticket guard

SDesk currently creates two tickets for a single return request — return #DRT202666-R1 produced tickets 5PJC3Y and Q2GZFC on 17 Aug 2026, and only one got answered. Any automated reply layer would double-message customers or answer the copy nobody is reading.

So sdesk_reply refuses with HTTP 409 when the ticket shares a return_id with other open tickets, and lists them. Merge or close the duplicate, or pass allowDuplicates: true to override. This is a guard rail, not a fix — the root cause is still in the return webhooks (webhooks.returns.request.tsx).

Safety note

sdesk_reply reaches a real customer's inbox and cannot be undone. Use sdesk_add_note to stage drafts when you want a human to press send.