MCP Server

Connect ChatGPT, Claude or another AI assistant to your Nimbu site and you can ask it to do the work for you in plain language: "find the product called Winter Jacket and lower its price to €89", "translate the About page to French", "which orders came in this week?". The assistant looks things up and makes changes on your site as you.

This works through the Model Context Protocol (MCP), an open standard that lets AI assistants talk to other services. You don't need to know how it works. All you need is this address:

https://mcp.nimbu.io/mcp

Copy it exactly, including /mcp at the end. A small typo, such as .be instead of .io or a missing /mcp, is enough for the connection to fail.

Before you start

You need a Nimbu account that has access to the site, and you sign in with your normal Nimbu login. The assistant can never do more than you can do yourself on that site.

Your assistant also has to support custom MCP servers. ChatGPT and Claude both do, depending on your plan. In a company workspace, an admin may have to allow it first.

You connect once, and it takes a couple of minutes. Each connection is for one site, so if you work on several Nimbu sites, connect once per site.

Connect ChatGPT

Share it with your team

The plugin you created is personal: only you see it. If you manage your company's ChatGPT workspace, open the plugin through ··· → Manage and click Publish to workspace so your colleagues can add it too. Everyone still signs in with their own Nimbu account, so each person keeps their own permissions.

Connect Claude

On a Free, Pro or Max plan:

1. In Claude, go to Customize → Connectors.
2. Click + Add and choose Add custom connector.
3. Enter Nimbu as the name and https://mcp.nimbu.io/mcp as the URL, then click Continue.
4. Leave the authentication settings as they are and click Add.
5. Click Connect next to Nimbu. Claude sends you to the Nimbu page from step 5 above: sign in, pick your site and click Grant access.

On a Team or Enterprise plan, an owner adds the connector once for the whole organisation under Organization settings → Connectors (Add → Custom → Web, same name and URL). Each member then goes to Customize → Connectors, finds Nimbu and clicks Connect.

To use Nimbu in a conversation, click the + button at the bottom left of the message box, open Connectors and make sure Nimbu is switched on.

For Claude Code, add the server from a terminal and follow the browser prompt:

claude mcp add --transport http nimbu https://mcp.nimbu.io/mcp

Other MCP clients

This section is for developers and tools like Cursor or VS Code.

The server speaks Streamable HTTP on a single stateless endpoint and returns JSON (no SSE stream, no session id). Enter the URL exactly as shown: some clients compare it character by character with the address the server reports during setup. For OAuth, clients discover everything from the server:

• Protected resource metadata: https://mcp.nimbu.io/.well-known/oauth-protected-resource
• OAuth 2.1 authorization code flow with PKCE (S256)
• Client registration through dynamic client registration or a Client ID Metadata Document

If your client can't do OAuth, create an MCP access token and send it as a bearer token. For clients configured with an mcp.json file (Cursor, VS Code and others):

{
  "mcpServers": {
    "nimbu": {
      "url": "https://mcp.nimbu.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-mcp-token>"
      }
    }
  }
}

With Claude Code:

claude mcp add --transport http nimbu https://mcp.nimbu.io/mcp \
  --header "Authorization: Bearer <your-mcp-token>"

The Nimbu consent page

Whenever an assistant connects through OAuth, Nimbu shows a consent page before anything is granted. From top to bottom:

• The app that is asking, with the domain it comes from below its name (for example chatgpt.com or claude.ai). Anyone can give an app any name, so when a client is identified only by its domain, Nimbu says so in a yellow warning. Trust the domain, not the name.
• Where you end up after approving ("After you approve, you'll be sent to …"). A desktop or command-line client shows an address on your own device instead.
• A table with a Read and a Write column for content and pages, channels, sensitive channels, customers, orders, products and themes. A check mark means the app gets that access, a dash means it doesn't. Rows labelled personal data cover information about people.
• Grant access to, where you pick one of the sites your account can use.

You can't switch off individual rows on this page: the table shows what the app asked for. What the app can actually do is also limited by your own role on the site, see Permissions. In ChatGPT, developers can narrow the request under Advanced OAuth settings when they create the server.

Access tokens issued through OAuth last two hours and the client refreshes them in the background. If a client later needs a permission you didn't grant, it can ask again and you'll see the consent page for the extra access.

Permissions

A connection can use two things at once: the scopes you approved, and your own permissions on the selected site. Both have to allow an action. If an admin narrows your role later, the connection narrows with it on the next request. It stops working altogether if your account is locked, you lose access to the site, or the connection is revoked.

These are the scopes an MCP connection can request:

A few rules follow from how scopes are checked:

• A write scope includes its read scope. write_content is enough to read pages.
• Tools the connection can't use are hidden. A connection without write scopes never sees the write tools in its tool list, so the assistant can't even try to call them.
• search, fetch, list_sites and get_site need no scope. search and fetch only return the kinds of records your scopes allow.
• A connection with no scopes at all only sees its own connection details.

Orders and customers are read-only through MCP. There are no write scopes for them.

Revoke access

Connections and tokens are listed in the Nimbu admin under Settings → Apps:

• Connected AI agents lists every OAuth connection to the site, with the user it acts as and when it was last used. Click Disconnect to revoke one.
• MCP Access Tokens lists the dedicated tokens. Click Revoke and confirm to delete one.

Revoking takes effect right away. If you don't see Apps in the settings menu, ask someone who manages the site's settings to disconnect the assistant for you.

MCP access tokens

For clients that take a token in their configuration instead of doing OAuth (Cursor, VS Code, CI jobs, your own scripts), create a dedicated MCP access token:

1. Go to Settings → Apps and click Create new MCP token in the MCP Access Tokens section.
2. Give it a name you'll recognise later, and pick only the scopes the assistant needs.
3. Pick an expiry: 90 days, 1 year (the default) or never.
4. Save and copy the token into your client's configuration.

An MCP token acts as the user who created it, on the site it was created for, and it follows that user's permissions just like an OAuth connection. It only works on mcp.nimbu.io; the REST API at api.nimbu.io rejects it. The reverse is true as well: a regular Site Access Token or REST token won't work on the MCP server. Create one MCP token per assistant so you can revoke one without touching the others.

Tools

The server exposes 37 tools. Your client shows the subset your scopes allow.

Search

Customers and orders hold personal data, so search leaves them out unless the request names them and the connection has read_customers or read_orders.

Pass a result's id to fetch unchanged. Types the connection has no scope for are dropped, and the response's types lists what was actually searched. degraded: true means the search for one type failed and its results are missing, so retry instead of treating the answer as complete.

Pages and navigation

Page edits are protected against overwriting someone else's work. update_page and update_page_content need the content_etag from a recent get_page; if the page changed in the meantime, the write is refused and the assistant has to read the page again. delete_page only proceeds when the assistant passes the page's current title.

Channels and translations

Channels marked as privacy-sensitive also need read_sensitive_channels or write_sensitive_channels. Per-entry access rules apply to MCP just as they do to the API.

On channels with publishing enabled, create_channel_entry and update_channel_entry take two arguments for the publication state:

• status: draft, published or scheduled. A create without status is a draft; an update without it leaves the state alone.
• publish_at: an ISO 8601 timestamp, required when status is scheduled.

An unknown status, scheduled without publish_at, or a malformed timestamp is refused before anything is written. On a channel without publishing, passing status returns a 422. To find unpublished entries, call query_channel_entries with filters: {"_status": "draft"} (or published, scheduled).

Products, orders and customers

Stock and inventory fields are ignored on product writes. Customer passwords and tokens are never returned, and you can't filter customers on them.

Files

An upload returns a file_ref that the assistant can put in an image or file field of a channel entry or product. Channel entries, products and pages can also take a small file inline in the same write call.

Theme

A theme file that someone last edited in the Nimbu admin is locked, and update_theme_file won't overwrite it.

Site

Tools never take a site argument. To work on another site, connect again and pick that site.

Languages

Content tools for pages, menus, channel entries, products, collections, translations, search and fetch take an optional locale argument, such as "nl" or "fr". Leave it out and the tool uses the site's default language. A write with locale only changes that language and leaves the others alone. A language the site hasn't enabled is refused; get_site lists the enabled ones.

Page reads always include every language under translations, whatever locale you pass.

Writes and retries

• create_page, create_channel_entry, create_product and upload_file require an idempotency_key (a UUID). Retrying with the same key and the same input returns the original result instead of creating a duplicate. The same key with different input is refused with idempotency_conflict. While the first attempt is still running, or when its outcome is unknown, the answer is idempotency_in_progress: check whether the record exists, and don't retry with a new key.
• update_product and update_channel_entry are not idempotent. Repeating an update can apply an increment twice or add another file or nested record. After a timeout or a lost response, read the record again and check what changed before you retry.
• update_page_content needs the page's current content_etag, so a retry after a write that did land is refused. Read the page again to see the result and get the new etag.
• Tools publish destructiveHint, idempotentHint and openWorldHint annotations. They help a client explain what a tool does, but they are hints, not a permission or confirmation check.

Limits

• Uploads are limited to 700 KB after base64 decoding, for upload_file and for inline files. Accepted types are PNG, JPEG, GIF, WebP and PDF. SVG is not accepted. Use the Nimbu admin or the CLI for larger files.
• Each connection can make 600 read calls and 60 write calls per five minutes. search has its own budget that depends on how many record types and results it asks for. Over the limit, the server answers with 429 and a Retry-After header.
• A single request may batch at most 20 tool calls.
• Lists return at most 50 items per page. Responses over roughly 50 KB are cut short, so narrow a query with filters or a smaller per_page.
• Menus are read-only. Edit them in the Nimbu admin.
• Some things are deliberately not available through MCP: stock changes, order status changes, customer account actions, coupons, webhooks, site settings, Cloud Code, and bulk or filtered deletes.

For client developers

• Protocol version. The server checks the MCP-Protocol-Version header. It currently accepts 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05; without the header it assumes 2025-03-26. Any other value returns 400 unsupported_protocol_version, before authentication.
• Tool list changes. The server doesn't advertise listChanged and never sends notifications/tools/list_changed. The tool list still depends on the granted scopes, so call tools/list again after a scope step-up or when a call returns 403 insufficient_scope.
• Structured content. Every result has structuredContent and the same JSON in a text block. structuredContent is always an object: a list comes back as {"items": [...]}, while the text block keeps the bare array.
• Partial bulk writes. When a bulk write such as upsert_translations doesn't fully succeed, the tool returns an error with code: "multi_status", a summary and per-item results. Check each item's applied flag: some items may have been written.
• Client registration. Nimbu only issues public OAuth clients with PKCE and no client secret. Dynamic client registration requires token_endpoint_auth_method: "none". A Client ID Metadata Document that declares an auth method must prefer none or list it in token_endpoint_auth_methods_supported.

Security

• Give each assistant the fewest scopes that do the job. Start with read scopes and add write scopes when you actually want changes made.
• Watch for prompt injection. An assistant reads whatever your site contains, including text that visitors and customers typed into forms, orders or channel entries. That text can contain instructions aimed at the assistant. With write scopes granted, a client may carry out an allowed write without asking you first, so review what the assistant proposes before you let it act.
• Records the assistant reads, including customer and order data, are sent to the AI provider behind your assistant. Check that your agreement with that provider covers this data before you grant read_customers or read_orders.
• Disconnect assistants and revoke MCP tokens you no longer use under Settings → Apps.