When the connection will not come up

Work through these in order. The first two cover most of it.

1. Claude Desktop was not restarted

The config is read once at launch. A correct setup plus a running app equals no tools. Quit Claude Desktop fully and reopen it. In Claude Code, claude mcp list re-checks health live, so there is nothing to restart.

2. The key is not reaching the server

Check the server is actually up first:

A healthy server answers with a small JSON object that includes "auth":"required". If that works but tools do not, the key is the problem, not the network. An unauthenticated call is refused outright:

That returns an unauthorized error by design. Add your header and it should return the tool list:

If the header version still fails, the key is wrong, revoked, or was pasted with a trailing newline. Re-copy it.

3. The shop is not in scope

A key is bound to the shops it may act on. Calling a tool with a different shop_id is refused even though the key is valid, which reads like a broken connection but is the scope check doing its job. Confirm you are passing the exact domain the key was issued for, in full your-store.myshopify.com form rather than just the store name.

4. Claude can see the tools but never uses them

Usually the request is too vague. Name the server and the job:

Using the gemboss MCP server, run a capture digest for https://example.com.

If it still refuses, ask it to list the tools it can see. A short or empty list means the connection, not the wording.

5. Two servers, two keys

The build tools (gem.*, gemtheme.*) and the read-only analytics tools (gemboss.*) are different servers. A key for one will not authenticate the other. If half the tools work and half do not, this is why.

Still stuck

Send us the shop domain, which client you are using, and what claude mcp list prints. Never send the key itself.