# MCP

Give your assistant access to Fusara models and generation.

Connect an MCP-compatible assistant to Fusara to discover models, estimate prices, create generations and retrieve results. MCP uses the same operations, model schemas, pricing and account balance as API v3.

## Connection details

| Setting | Value |
| --- | --- |
| Server URL | `https://fusara.ai/mcp` |
| Transport | Streamable HTTP |
| API-key header | `Authorization: Bearer YOUR_API_KEY` |

Get an API key from your [Fusara profile](/app/profile). Supply it through your client's credential settings or environment, never in the server URL or a conversation. The examples below keep the key out of configuration files.

For local clients, set `FUSARA_API_KEY` in the environment that launches the client. An already running editor does not inherit variables from a terminal opened afterward. These configurations use your API key; they do not require an OAuth login.

The MCP endpoint is a protocol endpoint. Opening it as an ordinary web page is not a connection test. This page at `/api/mcp` is the human-readable guide.

## Codex

Run this in the environment where `FUSARA_API_KEY` is set:

```bash
codex mcp add fusara --url https://fusara.ai/mcp --bearer-token-env-var FUSARA_API_KEY
```

Start a new Codex session and use `/mcp` to check the connection. The equivalent `~/.codex/config.toml` entry, also used by the IDE extension, is:

```toml
[mcp_servers.fusara]
url = "https://fusara.ai/mcp"
bearer_token_env_var = "FUSARA_API_KEY"
```

Use either setup method. See [Codex MCP configuration](https://developers.openai.com/codex/mcp/) for client-specific configuration locations.

## Claude Code

Merge this into your project's `.mcp.json`, then start Claude Code from the environment containing `FUSARA_API_KEY`. Approve the project server when prompted and check `/mcp`.

```json
{
  "mcpServers": {
    "fusara": {
      "type": "http",
      "url": "https://fusara.ai/mcp",
      "headers": { "Authorization": "Bearer ${FUSARA_API_KEY}" }
    }
  }
}
```

The variable reference stays in the file; Claude Code resolves it when connecting. See [Claude Code MCP setup](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcpjson).

## Cursor

Merge this into `~/.cursor/mcp.json` for your personal configuration, or `.cursor/mcp.json` for this project. Restart Cursor with `FUSARA_API_KEY` available to its process, then check the Fusara server in its MCP settings.

```json
{
  "mcpServers": {
    "fusara": {
      "url": "https://fusara.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:FUSARA_API_KEY}" }
    }
  }
}
```

Cursor uses `${env:NAME}` syntax, which differs from Claude Code's `${NAME}`. See [Cursor MCP configuration](https://cursor.com/docs/mcp#config-interpolation).

## VS Code

Use **MCP: Open User Configuration**, or merge this into `.vscode/mcp.json` for your project. Start VS Code with `FUSARA_API_KEY` available in the environment that connects to the server. Select **Start** for Fusara in the configuration editor and review the server trust prompt.

```json
{
  "servers": {
    "fusara": {
      "type": "http",
      "url": "https://fusara.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:FUSARA_API_KEY}" }
    }
  }
}
```

VS Code uses `servers`, not `mcpServers`, at the top level. See [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

## Claude and ChatGPT

For Claude on the web or Desktop, open **Customize → Connectors → Add custom connector**, name it Fusara, and enter `https://fusara.ai/mcp`. For an API-key connection, select **No sign in** and add the request header `Authorization` with value `Bearer YOUR_API_KEY` in the connector's credential settings. This means API-key authentication, not anonymous Fusara access. Enable the connector for your conversation. Shared team connectors use the configured key's account; use OAuth when each member should connect their own account. See [Claude's connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

In ChatGPT, open **Plugins → + → Add custom MCP server**, enter the same URL and configure authentication before creating the connection. Availability depends on your account and workspace policy. See [ChatGPT's connection instructions](https://developers.openai.com/plugins/deploy/connect-chatgpt).

For OAuth, choose a **provided / existing OAuth client**, with no client secret and token endpoint authentication `none` where that setting is available:

| Client | Client ID | Registered redirect URI |
| --- | --- | --- |
| ChatGPT | `fusara.mcp.chatgpt` | `https://chatgpt.com/connector_platform_oauth_redirect` |
| Claude | `fusara.mcp.claude` | `https://claude.ai/api/mcp/auth_callback` |

Complete Fusara's sign-in and consent screen. Fusara currently accepts these exact registered clients and callbacks; automatic client registration and published-client-identity registration are not enabled. If your client's setup uses a different callback or cannot select an existing client, that OAuth flow needs support from Fusara before it can work. Use an API-key-capable client above in the meantime. [ChatGPT's provided-client settings](https://developers.openai.com/plugins/build/plugins#use-a-registered-oauth-client) describe this registration mode.

## Check the connection

Ask the assistant to list Fusara models, then read one with `get_model`. Both are read-only. You should see the tools listed below; a successful connection does not require generating anything.

If you get `401`, check that the key is valid and available to the actual client process, and send only one authentication method. A failed OAuth registration is a client configuration issue, not a reason to change your model parameters. Use `/api/v3/openapi.json` for documentation, not as the MCP server URL.

## Account access

An authorized connection can use all MCP operations for your account, including paid generation. OAuth uses one `mcp` scope; there is no separate read-only or generation permission to assemble. Your client may still ask for confirmation before executing a tool according to its own settings.

Authentication does not expose another user's runs or private media. Revoke a key or connected application through the corresponding Fusara account controls when you no longer need the connection.

## Available tools

| Tool | Purpose | REST equivalent |
| --- | --- | --- |
| `list_models` | Find available models. | `GET /models` |
| `get_model` | Read a model's request schema and defaults. | `GET /models/{model}` |
| `estimate_run` | Estimate the configured request. | `POST /run/estimate` |
| `run` | Start a generation. | `POST /run` |
| `get_run` | Retrieve one run and its result. | `GET /run/{id}` |
| `list_runs` | Browse or filter run history. | `GET /run` |
| `cancel_run` | Cancel a run before execution admission. | `POST /run/{id}/cancel` |
| `get_balance` | Read the account balance and reservations. | `GET /balance` |
| `import_media` | Import a media URL for reuse. | `POST /media` |

The server advertises the current tool schemas through MCP discovery. Use those schemas rather than constructing arguments from model names in a prompt.

`get_model` and `list_models` accept `include: "presentation"` for Workspace labels and controls. Omit it for the compact response; request validation and defaults are shared with REST.

## A useful first request

Try asking your connected assistant:

> Find an image model suitable for a product photo, show me the estimated cost for one square image, and wait for my approval before generating it.

The assistant can discover a model, inspect its accepted inputs and estimate the exact request before calling `run`. If you want it to act without an extra approval, say so in your own instructions; the client's tool policy still applies.

For a specific model, a typical sequence is `get_model` → `estimate_run` → `run` → `get_run`. A webhook is also available through `run` when your integration has a public receiver.

## Runs remain asynchronous

`run` can return while generation is queued or running. Preserve its numeric `id` and retrieve that run later. Do not call `run` repeatedly while waiting for an output. Stop progress checks when the status is `succeeded`, `failed` or `canceled`.

MCP's `run` tool accepts an optional `idempotency_key` argument. It maps to the same mechanism as the REST `Idempotency-Key` header. Keep the key and request unchanged when retrying the same intended generation.

Tool responses include structured content and a JSON text representation. A tool invocation error is marked with `isError`; a successful `get_run` call can still contain a run whose generation status is `failed`. Inspect both levels.

For tool invocation errors, `_meta.http_status` carries the API status and `_meta.retry_after`, when present, is the minimum delay in seconds. Tool descriptions include the method's errors and recovery guidance from the same OpenAPI contract. For `request_in_progress`, wait and repeat the same `idempotency_key` and arguments. Follow the same [error and retry rules](/api/errors).

## Documentation for assistants

Share the [OpenAPI schema](/api/v3/openapi.json) with an assistant for REST methods and their request and response formats. For model-specific inputs and defaults, use `get_model` and its `request_schema`. Connected MCP clients discover tool schemas directly from the server.

Every guide and reference method has a **Markdown** link for sharing the instructions themselves. For application integration without an MCP client, start with the [API Quickstart](/api).