> ## Documentation Index
> Fetch the complete documentation index at: https://www.recraft.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

Recraft supports the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), enabling AI agents such as Claude, Cursor, and other MCP-compatible clients to interact with Recraft’s image generation and editing tools through a standardized interface.

By connecting Recraft's MCP server to your client, you can generate and edit high-quality raster and vector images directly from your agent environment without switching tools.

Recraft offers two ways to connect:

* **Remote MCP server** — a hosted server at `https://mcp.recraft.ai/mcp` that requires no local installation. Authenticate via OAuth with your Recraft account and connect directly from any MCP-compatible client. Usage is billed against your Recraft **subscription credits** (the same balance used in the Recraft Studio app). See [Remote MCP server](./remote-server) for setup instructions.
* **Local MCP server** — a self-hosted server you run on your machine. Useful if you want to store generated images locally or need full control over the setup. Usage is billed against your **API units** balance (the same balance used by the [Recraft API](/api-reference/getting-started)) and requires a Recraft API key. See [Setup](/mcp-reference/local-server) for installation options.

<Note>
  The remote and local MCP servers draw from **different balances**. The remote server consumes **subscription credits** from your Recraft plan, while the local server consumes **API units** purchased separately. Choose the option that matches the balance you want to use.
</Note>

## Supported operations

Both Recraft’s MCP servers expose the following operations:

* Raster and vector image generation
* Raster and vector image transforms
* Creating and using custom styles
* Vectorization of raster images
* Background removal and replacement
* Upscaling of raster images

For the source code of the Local MCP Server, visit [Recraft MCP GitHub](https://github.com/recraft-ai/mcp-recraft-server).

## Choosing remote vs. local

Use this comparison to decide which option fits your workflow:

|                | Remote MCP server                                                     | Local MCP server                                                                  |
| :------------- | :-------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| Installation   | None — hosted at `https://mcp.recraft.ai/mcp`                         | Requires Node.js, or install via DXT / Smithery                                   |
| Authentication | OAuth 2.0 with your Recraft account                                   | Recraft API key                                                                   |
| Billing        | **Subscription credits** (same balance as the Recraft Studio web app) | **API units** (same balance as the [Recraft API](/api-reference/getting-started)) |
| Result storage | Hosted by Recraft; clients receive URLs                               | Local directory (default) or hosted; configurable                                 |
| Best for       | Fast setup, Claude App / web clients                                  | Local file output, custom environments, users on a pay-as-you-go API plan         |

See [Remote MCP server](/mcp-reference/remote-server) or [Local MCP server](/mcp-reference/local-server) for setup details.

## Supported clients

Any MCP-compatible client that supports the Streamable HTTP transport and OAuth can use the remote server; any client that supports stdio-based servers can use the local server.

## Troubleshooting

### Remote MCP server

* **OAuth window doesn't open or loops back.** Clear the cached OAuth state in your client and reconnect. For `mcp-remote`, delete `~/.mcp-auth/` (or the equivalent directory for your OS) and restart the client.
* **Tools don't appear in the client.** Confirm the connector is enabled in your client's tools menu. In Claude Code, run `/mcp` to verify the server is connected and authenticated.
* **"Insufficient credits" errors.** Top up your subscription credits on the [Recraft web platform](https://www.recraft.ai). Remote MCP calls deduct from this balance, not from your API units.

### Local MCP server

* **`401 Unauthorized` from the API.** Check that `RECRAFT_API_KEY` is set in the client config and that your API units balance is greater than zero on the [API page](https://www.recraft.ai/profile/api).
* **Server doesn't start.** Verify Node.js is installed and that the config file path is correct for your client. Restart the client after editing the config so it re-reads the MCP server list.
* **"API units depleted" errors.** Buy additional API units from your [profile page](https://www.recraft.ai/profile/api). API units are separate from subscription credits.

### Either server

* **Generation succeeds but no image preview is shown.** Some clients impose a size limit on inline images. Retry with a smaller `size`, or open the returned URL directly.
* **Tools call appears to hang.** Image operations can take up to a few minutes for large outputs or upscales. Wait for the call to time out before retrying.