Connect an AI agent (MCP)

Every Flowkiwi instance exposes a Model Context Protocol (MCP) server. Point an AI agent at it and the agent can read your catalog (products, categories, collections, channels, …) and, if you allow it, update it - with your permissions, on the instance you choose.

You only give the agent a URL. There is no token, API key or header helper to set up: the agent signs you in through your browser and keeps its access fresh on its own.

Set up your client

Claude claude.ai, Claude Desktop and Claude Code.

Cursor An mcp.json entry with the server url.

VS Code GitHub Copilot agent mode, through .vscode/mcp.json.

Any other client that supports remote MCP servers over streamable HTTP with OAuth works the same way: give it the endpoint below. ChatGPT, for example, can add custom MCP servers in developer mode on some plans - see OpenAI’s documentation.

Endpoint

The MCP server runs on the Product Management host of each instance, at /api/mcp, over streamable HTTP:

https://<tenant>.product-management.flowkiwi.net/api/mcp

<tenant> is your instance handle, the same one you use to call the Product Management API. Sign in below and pick your instance to fill it into every snippet on this page. This sign-in only serves the docs; the agent signs in on its own.

Sign in to drop your real token into the commands below.

One connection per instance

The access an agent receives is bound to the exact URL it connected to. It is rejected on another instance, on another MCP server and on the REST API. To work on several instances, add one server per instance.

Prerequisites

• A Flowkiwi account that is a partner member of an organization with access to the instance, holding at least one permission there.
• You have signed in to the partner app at least once (your partner profile is created on the first sign-in).

How the sign-in works

The first time the agent calls the server, it runs a standard OAuth 2.1 authorization flow:

1. The server answers 401 and tells the agent where to authenticate: the Flowkiwi identity service.
2. The agent registers itself with Flowkiwi and opens your browser.
3. You sign in with your Flowkiwi account, as in the partner app.
4. A Flowkiwi consent screen shows the agent, the server and the instance. You pick the organization (only asked when several of your organizations can act on this instance) and the access level, then approve.
5. The agent receives its tokens and goes back to your conversation. From then on it refreshes its access by itself.

The consent screen shows the agent’s verified domain when the agent identifies itself with a metadata document (for example, Claude Code is shown as “Claude Code” with “claude.ai”), and marks it as unverified when the agent registers dynamically. Both work. Approve only agents you started yourself.

Access levels

Access level	What the agent can do
Read-only	Read with the *:read permissions you hold. Write tools are not offered at all.
Read and write	Use every permission you hold on the instance, reads and writes.

The agent never gets more than you have: its permissions are recomputed from yours each time it refreshes its access, so a permission removed from you is removed from the agent too. The server only lists the tools those permissions allow.

Write tools are flagged as such, and their description asks the agent to get your confirmation before changing anything. Most clients, such as Claude Code and Cursor, also ask your approval before they run a tool.

Available tools

The tools mirror the Product Management API: same filters, same validation, same permissions, same webhooks on writes.

Tool	Access	What it does
get_product	Read	Read one product.
list_products	Read	List and filter products.
list_categories	Read	List and filter categories.
list_collections	Read	List and filter collections.
list_channels	Read	List and filter channels.
list_countries	Read	List the countries of the instance.
list_locales	Read	List the locales of the instance.
list_statuses	Read	List the product statuses.
list_recent_changes	Read	List the most recently updated products, variants, categories, collections and channels.
update_product	Write	Update a product.
update_channel	Write	Update a channel.

The list grows over time. Your agent always sees the current tools of the API version it uses.

Choose the API version

Like the REST API, the MCP server is versioned. Send the Flowkiwi-Api-Version header to pin a version:

Flowkiwi-Api-Version: 2026-07

Without it, the server uses the oldest supported version and its responses carry a Deprecation header. Only clients that let you set custom headers can pin a version; the client pages show how. See API versions for the available versions and their support window.

Revoke an agent

In the partner app, the Connected agents page lists every agent connected to your account, with its server, organization, access level, connection date and last use. Revoke cuts an agent off.

Note

An access token already issued stays valid until it expires, so a revoked agent can keep working for up to 10 minutes.

To reconnect later, start the sign-in again from the agent: it goes through the consent screen as on the first connection.

Troubleshooting

Access denied after the sign-in

The consent step refuses access when none of your organizations can act on the instance: you are not a partner member of an organization with access to it, or you hold no permission there. Ask an administrator of the organization to add you, or check the instance handle in the URL. If you never signed in to the partner app, sign in there once, then retry.

The agent keeps getting 401

• Check the URL: the access is bound to the exact instance URL used at sign-in. A typo, another instance or a missing /api/mcp path asks for a new sign-in.
• If the connection was revoked, or not used for a long time, the agent has to sign in again.
• Clear the agent’s stored authentication and sign in again. Each client page explains how.

The agent uses an old API version

The server falls back to the oldest supported version when no Flowkiwi-Api-Version header is sent. Add the header in the client configuration if your client supports it.

Corporate network or proxy

• Desktop and editor clients connect from your machine: it must reach <tenant>.product-management.flowkiwi.net and identity.flowkiwi.net, and your browser must be able to open the Flowkiwi sign-in page.
• At the end of the sign-in, the browser redirects back to the agent running on your machine. Security tools that block these redirects break the sign-in.
• A proxy that inspects TLS with its own certificate must be trusted by the agent. Ask your IT team to add its certificate authority to the agent, following the agent’s documentation.
• claude.ai and Claude Desktop connectors connect from Anthropic’s cloud, not from your network.