Custom DesignerCustomDesignerDocumentation

MCP for Claude and ChatGPT

Custom Designer MCP

Any AI client that speaks Model Context Protocol over Streamable HTTP can call the same staff tools the in-app assistant uses: clients, orders, the production schedule, catalog search, Quick Quote, and approval links.

The server lives on the main app at /mcp. Any MCP client can connect with OAuth 2.1 (dynamic client registration, PKCE S256, shop-owner consent, scope read) or a company Developer API key from Settings → Developer (the same 64-character token as /api/v1). The token chooses the company. Do not send company_id. Tools are read-only.

Environment MCP URL
Production https://customdesigner.ai/mcp
Local http://localhost:3000/mcp or http://customdesigner.localhost/mcp

A browser that opens that URL is redirected to the in-app guide at /docs/integrations/mcp. Clients must POST JSON-RPC, not open the page.

Token

  1. Sign in and select the company the assistant should use.
  2. Open Settings → Developer.
  3. Generate a bearer token and copy it once. Regenerating revokes the previous token.

Send it on every MCP request:

Authorization: Bearer <64 hex token>

X-Api-Key: <64 hex token> also works.

Any AI app can connect via OAuth: discover /.well-known/oauth-authorization-server, register a public client, complete PKCE S256, and have the shop owner approve read access on the consent screen (app name + redirect host). HTTPS redirect URIs are accepted by default (http://localhost and http://127.0.0.1 for local tools). The authorize/token redirect_uri must exactly match a URI the client registered. API-key auth remains supported on the same /mcp URL.

The token shares the Integration API limit of about 300 requests per minute.

Tools

Read-only tools: whoami, orders_list, orders_get, order_statuses_list, orders_schedule, quotes_catalog, quotes_calculate, public_quote_links_list, customers_list, customers_get, products_search, products_get, purchase_orders_list, purchase_order_status, taxes_list.

There is also a company://profile resource and a shop-snapshot prompt. Write tools are not on this server.

These chat-only actions are not on this server: opening or refreshing a shop page, charts, web search, and customer-widget tools that identify a shopper by email.

Claude

Claude.ai and Claude Desktop can attach a remote MCP server and store a fixed bearer token.

  1. Open Customize (Claude.ai) or Settings → Connectors (Claude Desktop).
  2. Add a custom connector.
  3. Name it Custom Designer. URL: https://customdesigner.ai/mcp (or your local origin while testing).
  4. Open Request headers. Header name Authorization. Value Bearer plus the token, including the space. Claude sends the value exactly as entered and does not add Bearer for you.
  5. Save, then start a chat and ask something like “Find the client Acme and tell me their latest order status.”

The connector is organization-wide: everyone who can use it acts as that company token. Tools are read-only.

Claude Code

claude mcp add --transport http customdesigner https://customdesigner.ai/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Or in .mcp.json:

{
  "mcpServers": {
    "customdesigner": {
      "type": "http",
      "url": "https://customdesigner.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

If that header is rejected, Claude Code reports a failed connection instead of falling back to OAuth. Check the token, then run claude mcp list.

ChatGPT

In the ChatGPT app

Workspace owners turn on developer mode under Workspace settings → Permissions & Roles → Connected Data / Create custom MCP connectors. Then Settings → Apps → Create (or Workspace settings → Apps → Create):

  1. MCP server URL: https://customdesigner.ai/mcp
  2. If the dialog can send a request header, set Authorization to Bearer YOUR_TOKEN (include the word Bearer and a space).
  3. Scan tools, then create the app. It shows up as a draft with a Dev label. Enable it and @ mention it in a chat.

ChatGPT’s app builder is built around OAuth. This server advertises OAuth 2.1 (DCR + PKCE S256, scope read) at /.well-known/oauth-authorization-server. You can complete that flow, or send a Developer API key with Authorization: Bearer. If you pick no authentication, every tool will answer that a token is required.

OpenAI Responses API

The API can call a remote MCP server and attach the Developer token on the tool. Put the raw 64-character token in authorization (the API adds Bearer). Keep require_approval on always while you are testing writes.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Find the client named Acme and summarize their latest order. Do not change any records.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "customdesigner",
        "server_url": "https://customdesigner.ai/mcp",
        "authorization": "YOUR_64_HEX_DEVELOPER_TOKEN",
        "require_approval": "always"
      }
    ]
  }'

Send authorization on every request. The Responses API does not store it.

Cursor and VS Code

Cursor, ~/.cursor/mcp.json:

{
  "mcpServers": {
    "customdesigner": {
      "url": "https://customdesigner.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

VS Code, .vscode/mcp.json:

{
  "servers": {
    "customdesigner": {
      "type": "http",
      "url": "https://customdesigner.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Restart the client after saving. Ask it to list tools, then try customers_list or whoami.

Try it locally

With pnpm dev running and a token from the sandbox company:

curl -sS http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $V1_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

A second call with "method":"tools/list" returns the tool names. "method":"tools/call" with "params":{"name":"customers_list","arguments":{"q":"acme"}} runs a search.

Troubleshooting

  • Tools say a Developer token is required. The header is missing, or the value is the token without Bearer on clients that do not add it (Claude request headers). Complete the OAuth 2.1 flow, or send an API key.
  • Invalid or revoked API token. Generate a new token. The old one stops working immediately.
  • Too many requests. The token hit the shared per-minute limit with /api/v1.
  • Browser shows the docs page. That is the redirect for humans. Point the client at the same URL with POST.
  • Claude or ChatGPT starts an OAuth login. That is supported for any MCP client. Discovery is /.well-known/oauth-authorization-server (authorize, token, register, PKCE S256, scope read). Confirm the app name and redirect host on the consent screen. You can still use a bearer API key instead.