MCP Server

Connect an AI agent to Mercel over the Model Context Protocol — a curated set of tools backed by your Mercel account.

Mercel ships a Model Context Protocol (MCP) server so AI agents — Claude, Cursor, and any MCP-capable client — can read and write your workspace through a curated set of tools. The server is a thin client over the Mercel API: every tool call is authenticated with a Mercel credential and enforced by the same permissions as a direct HTTP call.

It's a hosted Streamable-HTTP endpoint at https://mcp.mercel.app/mcp — nothing to install. Point any MCP-capable client at the URL and connect one of two ways:

Sign in with OAuth — one click, no token to manage. Recommended for clients that support remote-MCP authorization (Claude and others).
Use a bearer token — paste a Mercel API token. Works with any client that lets you set an Authorization header, and with scripts and programmatic clients.

Tools

The surface is deliberately small — the jobs an agent actually needs, not a 1:1 mirror of every API endpoint:

Tool	What it does
`get_me`	Identify the authenticated user.
`list_organizations`	List the organizations you belong to.
`list_workspaces` · `get_workspace`	Discover and inspect workspaces.
`search`	Search across a workspace.
`list_products` · `get_product`	Read products (`list_products` can page through the full catalog).
`create_product` · `update_product` · `delete_product`	Write products. `delete_product` is flagged destructive so clients can prompt for confirmation.

Write tools can be turned off entirely — see Read-only and toolset gating.

Connect with OAuth

Clients that support remote-MCP authorization can connect without you ever handling a token — Mercel is a full OAuth 2.1 authorization server (PKCE, dynamic client registration, and refresh tokens). Add the server URL and the client runs the handshake for you:

In your client, add an MCP server with the URL https://mcp.mercel.app/mcp — leave the token blank.
The client discovers Mercel's authorization server and opens your browser.
Sign in to Mercel (if you aren't already), then review the consent screen — it lists exactly which permissions the app is requesting (for example, Read products and Write products).
Approve, and the client receives short-lived access tokens automatically and refreshes them in the background. There's nothing to copy or paste.

Beyond the URL there's nothing to configure: the client finds the authorization server, registers itself, and walks the consent flow on its own.

What the app can do

The consent screen only ever offers a subset of your own permissions — you can hand an agent read-only access even if you can write. An app can never do more than you can: every tool call is re-checked against your live workspace role, so if your access is later reduced — or you leave the workspace — the app's reach narrows at the same moment, with no stale token to wait out.

Like a personal access token, an OAuth grant is user-level and spans every workspace you belong to, so the agent chooses a workspace per call — see Binding a workspace.

Review and disconnect

Every app you authorize appears under Settings → Account → Connected Apps in the admin dashboard, with the scopes it holds and when it was last active. Disconnect revokes its tokens immediately — the agent stops working on its next call.

Connect with a token

For clients that don't support OAuth — or for scripts and programmatic use — supply a Mercel API token as a bearer credential. Issue one from Settings → Developer → API keys in the admin; see Authentication for the difference between the two token types:

A personal access token (mercel_pat_…) acts as you across every workspace you belong to.
A workspace API key (mercel_sk_…) is bound to a single workspace.

The token is forwarded to the Mercel API and re-verified on every tool call, so a tool can never do more than the token's holder could do directly. A malformed or missing token is rejected at connect time with a 401; a well-formed but revoked or unauthorized token connects but returns an UNAUTHORIZED error on the first tool call.

Binding a workspace

A workspace API key (mercel_sk_…) is already scoped to one workspace — nothing else to do.

A user-level credential — a personal access token (mercel_pat_…) or an OAuth grant — spans every workspace you belong to, so workspace-scoped tools (list_products, get_workspace, …) need to know which workspace to act on. Provide it either way:

Send a Mercel-Workspace-Id header on the connection.
Or pass a workspaceId argument on an individual tool call, which overrides the connection default for that call.

Call list_workspaces first if you don't know the id.

Read-only and toolset gating

Two environment variables narrow what the server exposes on a deployment:

MERCEL_READ_ONLY=1 drops every write tool — create_product, update_product, and delete_product disappear, leaving a read-only surface. Useful for agents that should never mutate state.
MERCEL_TOOLSETS=products,search restricts the surface to a comma-separated allow-list of toolsets. Valid toolsets are products, workspaces, organizations, search, and account; an unknown name fails fast at startup.

Gating is a convenience that keeps an agent focused — it is not the security boundary. Permissions are always enforced server-side by the Mercel API regardless of which tools were advertised.