> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Use AI assistants to manage your LaunchMyStore store via Model Context Protocol
# Model Context Protocol (MCP) Integration
LaunchMyStore ships a built-in MCP server so AI assistants — Claude Desktop, Claude Code, Cursor, OpenAI Codex, and any other MCP-compatible client — can drive your store through natural language.
The server speaks **both** MCP transports on the same hostname:
* **Legacy HTTP+SSE** (MCP spec `2024-11-05`) at `/mcp/sse` — Claude Desktop, Claude Code, Cursor.
* **Streamable HTTP** (MCP spec `2025-03-26`) at `/mcp` — OpenAI Codex and other newer SDK-based clients.
Pick the transport that matches your client; both expose exactly the same tools, resources, and authentication.
**Using Claude on the web or mobile (claude.ai)?** Custom connectors authenticate with OAuth instead of a pasted token — see [Claude.ai Custom Connector](/mcp/claude-ai-connector).
**Nova AI & MCP share the same tools.** Both interfaces use the same tool definitions, so any capability available in Nova AI is also available through MCP. This document covers MCP setup — for tool details, see [Nova AI Tools](/nova/tools).
## What is MCP?
The Model Context Protocol is an open standard that lets AI assistants call external tools and read external resources. With MCP wired up to your store, you can:
* Ask the AI to update product prices or inventory
* Create and manage discount codes through conversation
* Pull sales analytics and dashboards
* Manage orders and fulfillments
* Update store settings, content, and themes
## Quick Start
### 1. Generate an MCP token
1. Open your LaunchMyStore admin.
2. Navigate to **Settings → AI Connector (MCP)**.
3. Click **Generate token**.
4. Copy the token shown — it's a long opaque string valid for **1 year**.
Treat the MCP token like a password. Anyone with it can call the MCP server as you. Never paste it into a public repo, screenshot, or chat.
To revoke a token, change your account password — every MCP token issued before the password change stops working immediately. We don't yet expose per-token revocation; this is on the roadmap.
### 2. Add the server to your MCP client
Pick the snippet that matches your client. The admin page (**Settings → AI Connector (MCP)**) generates each one pre-baked with your token — click the **Copy** button on the relevant tab.
#### Claude Desktop / Claude Code / Cursor (SSE)
Claude Desktop, Claude Code, and Cursor use the **legacy SSE transport**, so they all share the same JSON snippet pointing at `/mcp/sse`:
```json theme={null}
{
"mcpServers": {
"launchmystore": {
"type": "sse",
"url": "https://api.launchmystore.io/mcp/sse",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}
```
**Claude Desktop** — edit `claude_desktop_config.json`:
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Paste the snippet, save, and restart Claude Desktop.
**Claude Code** — create a `.mcp.json` at the root of your project (or add to `~/.claude.json` for user scope), paste the snippet, and run `/mcp` inside Claude Code to confirm the connection.
**Cursor** — open Cursor settings (`Cmd+,` / `Ctrl+,`), search for **MCP**, and paste the snippet into your MCP servers config.
#### OpenAI Codex (Streamable HTTP)
Codex speaks the newer **Streamable HTTP** transport, so it points at `/mcp` (not `/mcp/sse`) and uses TOML instead of JSON. The token is loaded from an environment variable rather than inlined.
1. Edit `~/.codex/config.toml` and add:
```toml theme={null}
[mcp_servers.launchmystore]
url = "https://api.launchmystore.io/mcp"
bearer_token_env_var = "LAUNCHMYSTORE_MCP_TOKEN"
startup_timeout_sec = 30
```
2. Export the token in the shell where you launch Codex:
```bash theme={null}
export LAUNCHMYSTORE_MCP_TOKEN="YOUR_MCP_TOKEN"
```
3. Restart Codex.
**Do not** point Codex at `/mcp/sse` — that's the legacy two-endpoint SSE handshake and Codex will fail with `Deserialize error: data did not match any variant of untagged enum JsonRpcMessage`. Codex must use `/mcp`.
### 3. Try a few commands
* "Show me my top selling products this month"
* "Create a 20% discount code for new customers"
* "Update the price of 'Classic T-Shirt' to \$29.99"
* "What orders need fulfillment today?"
## Available Tools
The MCP server exposes the same tools as Nova AI, organized by category:
List, create, update, and delete products and variants
View orders, create manual orders, update status, refunds
Organize products with categories
View and manage customer data
Sales reports, traffic data, product analytics
Create and manage discount codes
Content management for blogs and custom pages
Theme settings, sections, and blocks
Navigation menu management
Shipping, checkout, and store configuration
For a complete list of tools with parameters, see the [Tools Reference](/mcp/tools).
## Endpoints
| Method | Path | Purpose |
| -------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/mcp/info` | Public discovery. Returns server info, capabilities, and the endpoint map. |
| `POST` | `/mcp/token` | Mints a 1-year MCP token for the authenticated merchant. |
| `GET` | `/mcp/config` | Returns a paste-ready config snippet (`?client=claude\|claudeCode\|cursor\|codex`). If no `token` query is supplied, mints a fresh one. |
| `GET` | `/mcp/sse` | **Legacy SSE transport.** Opens the MCP event stream. First event delivered is `endpoint`, whose data is the messages URL the client must POST to. |
| `POST` | `/mcp/sse/message?sessionId=…` | **Legacy SSE transport.** Send a JSON-RPC request bound to an open SSE session. Returns 202 Accepted; the response is pushed back through the SSE stream as an `event: message`. |
| `POST` | `/mcp` | **Streamable HTTP transport.** JSON-RPC over HTTP. Requests return 200 with `application/json`. Notifications return 202 Accepted with no body. Supports batch arrays. |
| `GET` | `/mcp` | **Streamable HTTP transport.** Used by clients that want a server-initiated stream. LaunchMyStore is stateless and pushes nothing, so this returns 405 (spec-allowed). |
| `DELETE` | `/mcp` | **Streamable HTTP transport.** Session-termination hook. LaunchMyStore does not issue `Mcp-Session-Id`, so this is a no-op that always returns 200. |
| `GET` | `/mcp/tools` | Lists every tool the AI can call. |
| `GET` | `/mcp/resources` | Lists read-only resources. |
| `GET` | `/mcp/docs` | Returns the full tool catalogue as markdown. |
### Verifying the server
```bash theme={null}
curl https://api.launchmystore.io/mcp/info
```
Response:
```json theme={null}
{
"name": "launchmystore-mcp",
"version": "1.0.0",
"protocolVersion": "2025-03-26",
"serverUrl": "https://api.launchmystore.io",
"capabilities": {
"tools": { "listChanged": false },
"resources": { "subscribe": false, "listChanged": false },
"prompts": { "listChanged": false },
"logging": {}
},
"endpoints": {
"jsonrpc": "/mcp",
"sse": "/mcp/sse",
"token": "/mcp/token",
"config": "/mcp/config"
},
"documentation": "https://docs.launchmystore.io/mcp/overview"
}
```
## Transport details
### Legacy HTTP+SSE (Claude Desktop, Claude Code, Cursor)
The SSE transport follows the [MCP 2024-11-05 spec](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/):
1. The client opens `GET /mcp/sse` with `Authorization: Bearer …`.
2. The server immediately emits `event: endpoint\ndata: /mcp/sse/message?sessionId=\n\n`.
3. The client POSTs every JSON-RPC request to that messages URL with the same Bearer header. Each POST returns **202 Accepted** with no body.
4. The server pushes the matching JSON-RPC response back over the original SSE stream as `event: message\ndata: \n\n`.
5. Heartbeats (`: heartbeat `) keep proxies from idling the connection out.
### Streamable HTTP (OpenAI Codex)
Codex (and any other client implementing the [MCP 2025-03-26 Streamable HTTP transport](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/)) talks to the single `/mcp` endpoint:
1. The client POSTs JSON-RPC requests to `/mcp` with `Authorization: Bearer …`. Requests that have an `id` get a 200 response with `Content-Type: application/json` containing the JSON-RPC response. Batch arrays are supported.
2. **Notifications** (JSON-RPC messages without an `id`, such as `notifications/initialized`) receive **202 Accepted with no body** — per the JSON-RPC 2.0 spec the server MUST NOT reply to a notification.
3. `initialize` negotiates the protocol version: the server echoes the client's requested version when it's one of `2024-11-05`, `2025-03-26`, or `2025-06-18`, otherwise falls back to its default.
4. `GET /mcp` returns 405 (we're stateless and don't push server-initiated messages — explicitly allowed by the spec).
5. `DELETE /mcp` returns 200 (we don't issue `Mcp-Session-Id`, so there's nothing to release).
You can hit either transport with curl. Plain request/response with the Streamable HTTP endpoint:
```bash theme={null}
curl -X POST https://api.launchmystore.io/mcp \
-H "Authorization: Bearer YOUR_MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/list",
"params": {}
}'
```
## Security
* Tokens are scoped to a single merchant account and inherit that account's role and permissions.
* Tool calls respect the same authorization model as the underlying REST APIs — if a role cannot delete products in the admin, the AI cannot delete them either.
* Changing the account password invalidates every issued MCP token in one step.
* All MCP tool calls land in your audit log with `source: "mcp"`.
## Troubleshooting
### Client shows "Connecting…" forever (Claude Desktop / Claude Code / Cursor)
Make sure your snippet includes `"type": "sse"` and points to `/mcp/sse` (not `/mcp`). The Streamable HTTP `/mcp` endpoint won't open an event stream for these clients — they expect the legacy two-endpoint SSE handshake.
### Codex: `Deserialize error: data did not match any variant of untagged enum JsonRpcMessage`
You pointed Codex at `/mcp/sse`. The legacy SSE handshake sends an `event: endpoint` frame as its first message, which Codex's Streamable HTTP parser can't interpret. Change `url` in `~/.codex/config.toml` from `https://api.launchmystore.io/mcp/sse` to `https://api.launchmystore.io/mcp`.
### Codex: `Transport channel closed, when send initialized notification`
Your backend is on an older build that returns a JSON-RPC response to notifications. The `/mcp` endpoint now returns 202 Accepted with no body for any payload without an `id`, which is what Codex expects. If you're self-hosting, pull the latest backend.
### "Unauthorized" / 401
Your token is invalid or expired. Generate a new one from **Settings → AI Connector (MCP)**.
### Tools don't appear
1. Confirm the connection is open in your client (Claude Code: `/mcp`).
2. Try `curl https://api.launchmystore.io/mcp/info` to verify the server is reachable.
3. Make sure your role has access to the tools you expect.
### Permission denied on a specific tool
The role tied to your MCP token doesn't have permission for that operation. Use an admin account or grant the relevant permission.