A request with an invalid key returns a normal invalid-token challenge. Confirm the key starts with `nb_sk_`, was copied from the creation screen, has not been revoked, and has the correct scope for the surface you are calling.

MCP client discovers OAuth but direct agents should not

Hosted chat apps may start a sign-in flow before they call MCP. Direct coding agents should send `Authorization: Bearer nb_sk_...` with every MCP request and do not need the chat-app connector flow.

Validation errors usually mean a required field is missing, an enum value is not allowed, or an array is empty. Check the tool or endpoint reference, then retry with IDs returned by `list_projects`, `list_product_images`, or `list_models`.

If a generation request fails because of credits, call `get_credits` or `GET /credits` before retrying. Lowering `variant_count` or output quality can reduce the credits needed for some requests.

Contact Novabrand support with the request time, endpoint or tool name, and the public error message. Do not send full API keys in support messages.

When to contact support

Fix common Novabrand integration issues: invalid API key, MCP OAuth discovery, generations that never complete, validation errors, and credit limits.

Troubleshooting the Novabrand API & MCP

Common integration issues and the checks that usually identify them quickly.

Troubleshooting

Novabrand Integration is a separate programmatic access service for accounts that want to automate creative production. Agents can discover projects, list available product and model images, generate ad creatives, generate model shots, and poll generation status.

Connect Claude Code, Codex, Cursor, Claude custom connectors, ChatGPT developer-mode connectors, Cowork, and compatible MCP clients.

MCP for agents

Call the same capabilities from your own trusted server-side workflow with an `api`-scoped Novabrand key.

Public REST API

`nb_sk_...` keys are scoped to `mcp`, `api`, or both. Chat-app OAuth also returns an MCP-scoped `nb_sk_` key.

One key model

Novabrand's MCP server and REST API let AI agents and apps generate ecommerce ad creatives and product photoshoots from your product images. Start here.

Novabrand API & MCP Docs for Ecommerce Ad Creatives

Generate ecommerce ad creatives and AI product photoshoots from your product images without booking a studio shoot. Novabrand exposes the same capabilities to MCP agents, chat-app connectors, and REST API clients.

Introduction

Novabrand programmatic access uses keys in the `nb_sk_...` format. Keys can include the `mcp` scope, the `api` scope, or both. Treat each key like a password: keep it server-side, do not commit it to source control, and rotate it if it is exposed.

Use the smallest scope that works for the client. An agent that only connects through MCP needs `mcp`. A server-side workflow that calls `/public/v1` needs `api`. Use both only when the same trusted environment needs both surfaces.

Revoking an API key immediately disconnects direct MCP clients, REST API callers, and chat-app connectors that received that key through OAuth.

Revocation behavior

Create and use scoped Novabrand API keys to authenticate MCP agents and REST API calls for AI ad creative and product photoshoot generation.

Novabrand API Authentication & API Keys (nb_sk)

Use scoped `nb_sk_...` API keys for MCP and REST. Create keys in Novabrand and send them only from trusted clients.

Authentication

novabrand

Novabrand

A successful `tools/call` returns the data inside `result.content` as a single text item whose `text` value is a JSON string. Parse that string to get the structured object. The field meanings for every tool are listed in MCP Tools.

When a tool rejects a request because of invalid input, a missing resource, or insufficient credits, it still returns a normal result with `isError: true` and a readable message in `text`. Malformed JSON-RPC or an unknown method returns a JSON-RPC `error` object instead.

Tool errors vs protocol errors

Agents should prefer IDs returned by Novabrand tools over user-typed IDs. Before generating, list the project assets and pass only product or model image UUIDs returned for that project.

Agent guidance

Connect Claude, Cursor, ChatGPT, and other MCP clients to Novabrand and generate ecommerce ad creatives and model photoshoots over JSON-RPC.

Novabrand MCP Server for AI Ad Creatives

Connect an agent client to Novabrand over JSON-RPC 2.0 using the MCP endpoint at `https://api.novabrand.ai/mcp`.

MCP Server

Some hosted chat apps do not ask users to paste a static API key for remote MCP servers. In those clients, Novabrand uses the standard OAuth connector flow: the user signs in, approves access, and the chat app receives a token it can use only for MCP.

Protected-resource metadata for MCP OAuth discovery.

Compatibility alias for clients that derive metadata from `/mcp`.

Coding agents and server-side tools that support bearer tokens can connect directly with an `mcp`-scoped `nb_sk_...` key. Hosted chat apps should use the OAuth connector flow when their UI asks the user to sign in.

Direct agents can still use API keys

Add Novabrand as an MCP connector in Claude, ChatGPT, or Cowork using OAuth 2.1 to generate ad creatives and product photoshoots without pasting an API key.

Connect Claude & ChatGPT to Novabrand via OAuth

Claude, ChatGPT, Cowork, and similar hosted connectors use OAuth 2.1 instead of asking users to paste a static API key.

Chat-App OAuth Connectors

list_product_images returns `product_images` and list_models returns `model_images`. Pass the `file_uuid` of each item as `product_image_uuids` or `model_image_uuids` when you generate.

check_brand_analysis and check_generation share the same status fields. Keep polling until the work finishes, then read the result.

When check_generation reports `completed: true`, the `asset` holds one entry per variation in `generated_assets`.

Free plans return generated images as watermarked previews while paid plans return the original-resolution images. Check `is_watermarked` before you publish an asset.

Watermarking

Each generation costs `variant_count` multiplied by a quality factor, so higher output quality costs more per image. The exact charge for a request is returned as `credits_used` when the generation starts.

How credits are counted

Reference for Novabrand's MCP tools to create projects, list product images, generate ad creatives and model photoshoots, and check credits.

Novabrand MCP Tools: Generate Ads & Model Shots

Novabrand exposes nine MCP tools for project discovery, setup, image lookup, generation, polling, and credit checks.

MCP Tools

Every REST endpoint requires an `api`-scoped key in the `Authorization` header. Async operations return `202 Accepted`; read operations and polling return `200 OK`.

Successful REST responses return a top-level `data` object. Failed requests return a top-level `error` object with `type` and `message` fields. Use the message for user-facing recovery and the type for programmatic branching. The object inside `data` matches the corresponding MCP tool result, so the field references in MCP Tools apply here too.

Branch on the HTTP status first. The `error.type` field gives a more specific reason for the same failure.

Use the Novabrand REST API to generate ecommerce ad creatives and AI model photoshoots from product images. Endpoints, request and response shapes, and errors.

Novabrand REST API for Ad Creative Generation

The REST API mirrors the MCP capabilities under `/public/v1` for direct server-side integrations.

REST API

Generate ad creatives from existing product images

Step-by-step Novabrand workflows to create projects, generate ad creatives, and run AI product photoshoots from your existing product images.

Novabrand Workflow Examples for AI Ad Creatives

Common workflows for humans, agents, and server-side automation using Novabrand integration docs.

Troubleshooting

Invalid token

MCP client discovers OAuth but direct agents should not

Generation starts but never completes

Validation errors

Credit errors