# Bria MCP Server

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets AI assistants and agents call external tools. Bria publishes an MCP server so any MCP client can generate and edit images and videos with Bria's models, with no custom integration and nothing to host.

There are two ways to run it:

|  | Hosted server (recommended) | Local server (stdio) |
|  --- | --- | --- |
| Endpoint | `https://mcp.prod.bria-api.com/mcp` (Streamable HTTP) | `uvx bria-mcp` on your machine |
| Authentication | `api_token` header, or OAuth 2.1 bearer token | `BRIA_API_TOKEN` environment variable |
| Maintenance | None. Bria runs, scales and secures it | Python 3.10+; updates via `uvx`/`pip` |
| Image inputs | Public image URLs (base64 where the client allows it) | Public URLs, local file paths, or base64 |
| Best for | Claude, Cursor, VS Code, ChatGPT, server-side agents | Desktop clients that launch a local command, offline files |


Both servers call the same [Bria REST API](/) with your account's plan and rate limits, and every result is commercially licensed like any other Bria output.

## Tools

The server exposes one tool per capability. Names below are the tool identifiers of the local `bria-mcp` server; the hosted server exposes the same capabilities.

| Area | Tool | What it does |
|  --- | --- | --- |
| Image generation | `text_to_image` | Text-to-image or image-to-image with FIBO (`FIBO` by default, `FIBO_LITE` for speed). Supports aspect ratio, negative prompt, seed. Returns the [structured prompt](/vgl) behind the image; feed it back to re-imagine the same scene with a different setting, lighting or style. |
| Image editing | `edit_image` | Natural-language edits that keep the rest of the image intact. Accepts up to 4 ordered images ("image 1", "image 2"...) to combine a subject with a style, background or object from another image. Optional seed and output aspect ratio. For garments or held products, use `virtual_tryon` or `product_holding`. |
|  | `product_holding` | Put a product in someone's hands from a person photo and 1 to 3 product images (packaging, a second angle, or a companion item); no prompt needed. Preserves the person's identity, pose and background and the product's geometry, colors, branding and label text. Optional instruction, output aspect ratio (defaults to the person image's) and seed. See [Product Holding](/product-shot-editing/products/product-holding). |
|  | `virtual_tryon` | Dress a person in 1 to 3 garment or accessory images in one call; no prompt needed. Preserves garment details (print scale, stripe alignment, collar and closure type) and the person's identity, pose and background. Optional instruction, output aspect ratio (defaults to the person image's) and seed. |
|  | `remove_background` | Cut out the subject on a transparent background. |
|  | `generate_background` | Replace the background from a prompt, reference images, or both. |
|  | `blur_background` | Depth-of-field blur, adjustable strength. |
|  | `crop_out_foreground` | Remove the background and crop tightly around the subject, with optional padding. |
|  | `erase_foreground` | Remove the subject and fill in the scene behind it. |
|  | `expand_image` | Outpaint to a new aspect ratio. |
|  | `increase_resolution` | Upscale 2x or 4x without inventing detail. |
|  | `enhance_image` | Sharper textures and richer detail, optionally upscaling. |
| Ads | `ad_to_layers` | Turn a flat ad into editable layers (background, imagery, logo, headline, body copy, CTA) with the [Ad Delayer](/ads). Runs 2 to 3 minutes; ads over 1350 px per side need an Enterprise plan. |
|  | `ad_resize` | Resize a finished, flat ad (PNG or JPG) into up to 10 named target sizes in one call. Each size is laid out again from editable layers through the [Ad Delayer](/ads), so the headline is re-set rather than stretched and the logo and product stay in frame. A call takes a few minutes and returns one URL per target size, with no inline image previews. Sources over 1350 px per side are downscaled first unless the plan is Enterprise, and the response says so. |
| Video | `remove_video_background` | Remove a video background (black or white replacement). |
|  | `increase_video_resolution` | Upscale a video 2x or 4x. |
|  | `video_mask_by_prompt` | Segmentation mask video from a text prompt. |
|  | `erase_from_video` | Erase an object from a video using a mask video or a prompt. |


## Connect a client

Get an API token from the [Bria Console](https://platform.bria.ai/organization-management/api-keys), then pick your client.

Claude Code
```bash
claude mcp add --transport http bria https://mcp.prod.bria-api.com/mcp \
  --header "api_token: $BRIA_API_TOKEN"
```

Cursor
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "bria": {
      "url": "https://mcp.prod.bria-api.com/mcp",
      "headers": { "api_token": "<your-bria-api-token>" }
    }
  }
}
```

VS Code
Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "bria": {
      "type": "http",
      "url": "https://mcp.prod.bria-api.com/mcp",
      "headers": { "api_token": "<your-bria-api-token>" }
    }
  }
}
```

Claude Desktop
Claude Desktop launches local servers. Run the local server with [`uvx`](https://docs.astral.sh/uv/) (downloads and runs [`bria-mcp`](https://pypi.org/project/bria-mcp/) on demand):

```json
{
  "mcpServers": {
    "bria": {
      "command": "uvx",
      "args": ["bria-mcp"],
      "env": { "BRIA_API_TOKEN": "<your-bria-api-token>" }
    }
  }
}
```

Or install once (`pip install bria-mcp`) and use `bria-mcp` as the command. Locally, images may be public URLs, local file paths, or base64 data.

Anthropic API
Let Claude call Bria server-side from the Messages API. The MCP connector authenticates with an OAuth bearer token (see [OAuth](#method-2-oauth-21-bearer-token)) and requires the `mcp_toolset` entry alongside `mcp_servers`:

```python
import os
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.prod.bria-api.com/mcp",
            "name": "bria",
            "authorization_token": os.environ["BRIA_OAUTH_TOKEN"],
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "bria"}],
    messages=[{"role": "user", "content": "Generate a packshot of a matte black travel mug on white."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
```

OpenAI API
The hosted MCP tool accepts custom headers, so the API token method works here:

```python
import os
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="<model>",
    tools=[{
        "type": "mcp",
        "server_label": "bria",
        "server_url": "https://mcp.prod.bria-api.com/mcp",
        "headers": {"api_token": os.environ["BRIA_API_TOKEN"]},
        "require_approval": "never",
    }],
    input="Remove the background from https://example.com/product.jpg",
)
print(response.output_text)
```

Any other MCP client that speaks Streamable HTTP with custom headers can use the hosted URL the same way; stdio-only clients use the local server.

## Authentication

All hosted requests are token-based. Choose the method that fits your client.

### Method 1: API token

Copy an API token from the [Bria Console](https://platform.bria.ai/organization-management/api-keys) and send it in the `api_token` header of every request to the MCP server. Tokens are long-lived, so there is no refresh logic to build. Treat the token as a secret: store it in an environment variable or a secret manager and never ship it in client-side code.

### Method 2: OAuth 2.1 bearer token

The hosted server implements the MCP authorization flow (OAuth 2.1 with PKCE, dynamic client registration and discovery at `https://mcp.prod.bria-api.com/.well-known/oauth-authorization-server`). Clients that support MCP OAuth prompt the user to sign in with their Bria account and then send the resulting bearer token on each request; access tokens expire and the client refreshes them automatically.

Use this method when end users should authorize with their own Bria accounts, or with platforms that only accept bearer tokens, such as the Anthropic MCP connector. Anthropic documents how to obtain a bearer token for testing in the [MCP connector guide](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector#obtaining-an-access-token-for-testing).

## Supported inputs

The server accepts JPEG, PNG and WEBP images. The hosted server takes publicly reachable image URLs (and base64 payloads where the client supports them); the local server also takes local file paths. Video tools take a publicly reachable video URL; for local files, upload them first with the [Video Upload Service](/local-video-upload-service).

## Outputs

Image tools return a JPEG preview (up to 0.7 MB) that the assistant can show inline, plus a URL to the full-quality result. Video and ad tools return result URLs only; open a URL to view or download the file.

## Errors

When the Bria API rejects a request, the tool returns an error result that tells you why, in the form `Bria API error <status code>: <reason>` (for example, an invalid parameter, an unsupported image, or an exhausted plan). The assistant sees the reason and can correct the request or explain the problem, rather than getting a generic "Error executing tool" message.

If an image input can't be read, for example when a local file path is sent to the hosted server, the tool returns the error `Could not read the image input. Pass a public image URL or base64 data - local file paths are only readable when the server runs on the same machine.` The assistant can then retry with a public URL or base64 data.

## Related

- [Agent skills](/integration-methods/bria-skill) for coding agents that prefer instructions and scripts over a tool server.
- [Python SDK](/integration-methods/python-sdk) for application code.
- [Bria for AI agents](/integration-methods/for-ai-agents): `llms.txt`, Markdown pages and the docs MCP server.