Connect with MCP

Connect EcomSquad through MCP (Model Context Protocol) to ask your assistant about support tickets without building an integration.

Before you begin

You need:

Access to your EcomSquad organization.
A mailbox with stored conversations, plus a Shopify store for order context.
An assistant that supports remote Streamable HTTP MCP servers.
The EcomSquad MCP URL:

MCP endpoint

https://api.meetwillow.cx/api/v1/mcp

If your sources are not ready, start with Connect your sources.

Choose how to connect

Use sign-in when your assistant supports MCP OAuth. Use an API key when it supports custom HTTP headers.

Add the server

In your assistant’s remote MCP or custom connector settings, add the MCP URL. Choose Streamable HTTP if asked for a transport.

For Claude Code, run:

Terminal

claude mcp add --transport http ecomsquad https://api.meetwillow.cx/api/v1/mcp

Start Claude Code and open /mcp to authenticate. See the Claude Code MCP documentation for its client controls.

Follow the client’s authentication prompt. Use your provisioned EcomSquad email address and the sign-in link sent to your inbox.

Review the client name, redirect destination, and requested access. Keep context reading enabled. Leave Refresh context from connected providers unchecked for this read-only walkthrough, if requested.

Return to your assistant

Confirm EcomSquad’s tools are available. With context:read, you should see the five read tools, including list_tickets and get_ticket.

The assistant uses your current membership permissions, narrowed by the access you approve.

Connect with an API key

Create a key

Follow Create a key. Give it Support context → Read and access to the mailbox and store you want to read.

Configure your client

Enter these values in the client’s private MCP settings:

Setting	Value
Transport	Streamable HTTP
URL	`https://api.meetwillow.cx/api/v1/mcp`
Header name	`x-api-key`
Header value	Your EcomSquad API key

Keep the secret in the client’s credential settings, not in a chat message. EcomConnect agent keys cannot authenticate this endpoint.

Check the tool list

Connect the client. With context:read, you should see the five read tools. Connection limits determine which records those tools can return.

Switching to sign-in?

Remove the x-api-key header first. It takes precedence over OAuth even when its value is empty or invalid.

Read your first ticket

Ask your assistant:

Use EcomSquad to list up to five tickets. Ask me which one to open, then read its messages and its stored orders. Explain which orders are verified and anything missing. Do not refresh it yet.

The assistant should call list_tickets, then use the selected ticket’s id as ticketId for get_ticket and get_ticket_messages.

Check your result

You should see the selected ticket’s messages and an explanation of its orders. Missing order information can be a valid result; the assistant should explain what is missing.

Common problems

No tools appear: check that the key or approved sign-in access includes context:read, then reconnect.
No tickets appear: check mailbox data and connection access. Only conversations the support classifier judged a support request have a ticket; see Tickets.

For repeated sign-in prompts or other errors, see MCP troubleshooting.

Tools

Each tool runs the same procedure as the REST operation beside it, takes the same inputs as JSON arguments, and returns the same data as JSON text.

Tool	Same as	Permission
`list_tickets`	List tickets	`context:read`
`get_ticket`	Get a ticket	`context:read`
`get_ticket_messages`	List ticket messages	`context:read`
`refresh_ticket`	Refresh a ticket	`context:refresh`
`get_order`	Get an order	`context:read`
`get_customer`	Get a customer	`context:read`
`refresh_inbox`	Refresh mailboxes	`inbox:refresh`, API key only
`get_inbox_refresh`	Get mailbox Refresh status	`inbox:refresh`, API key only

A client sees only the tools its permissions allow; calling a hidden tool fails like an unknown tool. Each call still checks the permission. The Needs reply feed has no MCP tool; it answers API keys only. The mailbox Refresh tools are offered to API keys only, never to sign-in. The tools never send email, issue refunds, or change merchant orders.

A key uses its permissions and connection limits. Sign-in uses your role, narrowed to the scopes you approve (context:read, context:refresh), and reaches connections like a key with no connection limits. Approving context:refresh also grants context:read. A missing or invalid key answers HTTP 401 before any tool runs; a sign-in whose membership has ended gets a 401 that asks the client to sign in again. A request with neither a key nor a token gets this JSON-RPC error:

No credentials

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Authentication required: send an API key in the x-api-key header, or an OAuth access token in the Authorization header"
  },
  "id": null
}

An invalid key gets the REST error body instead, with code UNAUTHORIZED.

A tool failure can arrive inside an HTTP 200 response: check the tool result’s isError flag. When the procedure fails, the text is the same JSON error body as REST, such as {"code":"NOT_FOUND","message":"Ticket not found"}. An unexpected failure returns INTERNAL_SERVER_ERROR with the message Tool call failed. Invalid arguments are refused before the procedure runs, as plain text starting Input validation error.

Every MCP response carries an x-request-id header, as the Context API does. Quote it when you report a problem.

Docs for assistants

Every page on this site is available as plain Markdown.

Resource	What it is
llms.txt	Index of every page with a one-line description. Point an assistant here first.
llms-full.txt	Every page as Markdown in one file, in sidebar order.
Per-page Markdown	Add `.md` to any page path, for example `/quickstart.md`. Each page also has Copy Markdown under its title.

Paste a page’s Markdown, or its .md link, into your assistant when you want it to follow a procedure exactly as written. Use llms.txt when it should decide which page applies. The documentation describes EcomSquad; your tickets come only from the MCP server or the Context API, scoped by your sign-in or key.

Learn which orders are verified before using a result to answer a customer.

On this page