# MCP server

URL: https://smartcut.dev/docs/mcp

> Run SmartCut cutting-pattern optimisations from your own LLM client (Claude, Cursor, custom agents) over the Model Context Protocol — authenticated with your existing API key.

SmartCut exposes its optimisation API as a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so an LLM client — Claude Desktop, Claude.ai, Cursor, or your own agent — can submit cutting jobs, fetch layouts and generate exports directly, in natural language.

It mirrors the [REST v3 API](/docs/api): same engine, same authentication, same usage quota. Anything you can do over REST you can do over MCP.

## Endpoint

```text
POST https://api.smartcut.dev/mcp
```

The transport is **Streamable HTTP**. There is no separate install — it's a hosted, remote MCP server; you point your client at the URL above and authenticate with your API key.

## Credentials

You authenticate with your **existing SmartCut API key** — there is no separate MCP token to create.

1. Sign in at [smartcut.dev/account](https://smartcut.dev/account) (an active **API subscription** is required).
2. Copy your **API key** from the account page.
3. Give it to your MCP client as an `Authorization` header (see below). The value is the **raw key — no `Bearer ` prefix**.

:::caution
Your API key is a secret. Store it in an environment variable rather than pasting it directly into a config file, and never commit it to source control.
:::

## Connect a client

Most LLM clients connect to a remote MCP server through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. Add SmartCut to your client's MCP config (e.g. Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "smartcut": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.smartcut.dev/mcp",
        "--header", "Authorization:${SMARTCUT_API_KEY}"
      ],
      "env": {
        "SMARTCUT_API_KEY": "your-api-key"
      }
    }
  }
}
```

Passing the key via the `env` block (rather than inline in `args`) keeps it out of the args list and avoids clients that strip spaces from arguments — note there is no space after `Authorization:`.

If your client supports remote/HTTP MCP servers **natively** (a URL plus custom headers), configure it directly instead:

- **URL**: `https://api.smartcut.dev/mcp`
- **Header**: `Authorization: <your-api-key>`

Restart the client and the SmartCut tools below become available.

## Tools

Each tool maps 1:1 to a v3 API endpoint:

| Tool | Does |
|---|---|
| `optimise` | Submit a job and (by default) wait in-call for the finished layout. |
| `validate` | Pre-flight your inputs (will the parts fit, why not) — no job is run and nothing is charged. |
| `status` | Check a job: queued / active / completed / failed / cancelled. |
| `result` | Fetch a finished layout by job id. |
| `cancel` | Cancel a queued or running job you own. |
| `usage` | Your plan usage: used / limit / remaining. |
| `export` | Generate a `pdf`, `csv`, `ptx`, `dxf`, `svg` or `mayer` file and return a download URL. |
| `labels` | Generate a printable labels PDF and return a download URL. |
| `list_cut_types` | The valid `stockType → cutType → cutPreference` combinations, so the model can build a correct request without leaving the chat. |

## How `optimise` runs

Optimisation is asynchronous, but the `optimise` tool bridges that to a single call:

1. It submits the job, then waits in-call (default up to ~25 s; override with `waitMs`).
2. If the job finishes in time, it returns the **full layout** there and then.
3. If it doesn't, it returns `{ jobId, status: "running" }`. The result still arrives at any `webhook` you supplied, and the model can fetch it later with the `result` tool.

This keeps normal jobs to one round-trip while large or batch jobs stay fully async.

## Billing & limits

The MCP and the REST API share **one quota**. An `optimise` call counts against your plan exactly like a `POST /v3/calculate`, and `validate` / `status` / `usage` are free. Rate limits are the same per-minute budget as the REST API. Result fetching is scoped to your own jobs.

## See also

- [API Reference](/docs/api) — the underlying REST v3 API and authentication.
- [Interactive v3 reference](/api-docs/v3) — every endpoint, live.
- [Store config MCP](/docs/ecommerce-mcp) — the e-commerce counterpart, for configuring a hosted storefront.