Skip to Content
LogoDevelopers
APIs & ToolsMCPAdmin MCP

Admin MCP

The Admin MCP server gives AI agents access to merchant administrative operations: catalog, orders, customers, themes, content, marketing, and store setup. It is the same tool surface Success Agent uses in the Finqu admin, exposed over the Model Context Protocol  for your own clients.

Use Admin MCP when an agent should act as the merchant. For customer-facing shopping agents, use UCP instead. To plug your APIs into Success Agent, use MCP Tools.

Endpoint

https://mcp.finqu.com/mcp

Transport

The server speaks Streamable HTTP MCP:

  • Path: /mcp
  • JSON responses enabled
  • Stateless (no MCP session store)
  • Capabilities: tools only (no resources or prompts)

Discover tools

Call MCP tools/list after you connect. For merchant OAuth tokens, the list always includes get_profile, list_channels, and all admin tools. Some tools only succeed on a suitable channel type — for example theme tools need a webstore channel. Missing scopes or permissions fail at call time, not by hiding tools. See Tools for a grouped catalog.

Upstream tool descriptions include an Example output: sample of a successful { "status": "ok", "response": … } payload.

Connecting an agent

Connect any external AI client or agent framework to Finqu Admin MCP:

  1. Add https://mcp.finqu.com/mcp to your MCP client configuration. Finqu Admin MCP supports Dynamic Client Registration (RFC 7591), so no pre-registered app or manual Bearer token is needed for supported editors and AI clients.
  2. Complete authorization in your browser when prompted by your client.
  3. Call tools as needed. Schemas that require channel_id advertise it; use list_channels to discover ids. See Sales channel.

Example MCP client config (Cursor / Claude Desktop HTTP server):

{
  "mcpServers": {
    "finqu-admin": {
      "url": "https://mcp.finqu.com/mcp"
    }
  }
}

For detailed client setup recipes (Claude Desktop, Cursor, Codex, VS Code, Gemini CLI, Claude Code, TypeScript SDK, and Python SDK), see Connecting Agents. For headless automation or environments without interactive OAuth support, a manual Bearer token can also be passed via the Authorization header. See Authentication.

Sales channel

Tools that need a sales channel advertise an integer channel_id parameter. Call list_channels to discover ids for the merchant on the token. get_profile and list_channels do not take a channel.

list_channels needs the profile, sales_channel_read, or sales_channel_write scope. It returns:

{
  "merchant_id": 42,
  "channels": [{ "id": 12345, "name": "Main store", "type": "webstore", "store": {} }]
}

get_profile returns the signed-in user, the merchant (id, name, hostname, currency_id, account_status), and the token’s scopes.

A missing channel_id is an MCP tool error (isError: true):

Validation Error: Missing required parameter 'channel_id'. Call the list_channels tool to discover available sales channels for this store.

A channel that does not belong to the merchant on the token is also a tool error:

Access Denied: The specified channel_id (12345) does not belong to the authorized merchant account.

Theme tools use the current or public release and the frontpage template for that channel.

Responses

Successful admin tool results are JSON:

{
  "status": "ok",
  "response": {}
}

get_profile and list_channels return their objects directly. They are not wrapped in status / response.

Admin tool failures set the MCP tool error flag. The payload is:

{
  "status": "error",
  "response": {
    "message": "Human-readable error",
    "code": "optional_stable_code",
    "suggestions": {}
  }
}

code and suggestions are omitted when unused. Common codes include release_missing, revision_mismatch, and write_failed.

Channel validation errors from Sales channel are plain text tool errors, not this envelope.

HTTP errors

StatusWhen
401Missing or invalid Authorization, invalid access token, inactive merchant, or a forwarded admin tool call from an unapproved OAuth client. The response includes WWW-Authenticate on unauthenticated requests
403The user is not a staff member of the merchant on the token
429A forwarded admin tool call exceeded the OAuth client’s rate limit

A 401 body looks like:

{
  "error": "unauthorized",
  "message": "Authorization header required."
}

Access control

For merchant OAuth tokens, all admin tools appear in tools/list. Calling them still requires:

  1. OAuth scopes on the access token (mapped to admin permissions — see Authentication)
  2. User permissions for that merchant and channel (staff accounts cannot exceed their admin role)
  3. Channel type — for example theme and navigation tools require a webstore channel, and marketing message and social tools require webstore or pos

OAuth clients do not receive merchant-configured extension MCP tools (servers added under AI Commerce → MCP Tools). Those stay inside Success Agent and Workers.

Partner access tokens on this URL do not receive the admin catalog.

Next steps