Skip to content
MSO CloudDocumentation

MCP server

On this page

In short. The MCP server lets an MCP-compatible client (Claude Desktop, Claude Code, Codex, Cursor) ask questions about one organization's metrics from your own machine. A super admin mints a per-organization token; a small bridge program you run locally turns client requests into HTTPS calls to the platform.

The client talks to a local bridge over stdio; the bridge calls the platform with a bearer token; the platform pins the organization, runs the same tools as the data assistant and writes an audit row

How it works#

  • Platform side. Two endpoints in the web application: one lists the tools, one runs a tool. Both require the token, apply the organization pinned to it, use Vietnam-time buckets and the same formulas as the data assistant, and write one audit-log row per call.
  • Bridge side. apps/mcp-server is a Node program in the repository, started with pnpm --filter @yng/mcp-server start from a checkout. It reads UCIP_API_URL and UCIP_API_TOKEN from its environment and fetches the tool list once at start, so a new tool reaches a client at its next restart.
  • Token. Only a super admin can mint it: open the organization in the console, tab "MCP tokens" ("Token MCP" in Vietnamese), enter a label and a lifetime (default 90 days, at most 365). The token is shown once and stored hashed. It belongs to the organization, not to a person; treat it as a service credential and pass it through a secrets manager.

Steps to connect#

  1. A super admin mints the token as above.
  2. Add the bridge to the client's MCP configuration as a stdio server, with the two environment variables, and restart the client.
  3. Ask the client to list the available metrics, then ask a real question. It should call a query tool and summarise the result.

Tools#

Tool Answers
List metrics, get context What can be measured, and the organization's context
Query metric A metric's total and trend for a period
Top N by dimension Top values by a group: platform, creator, SKU
Compare across periods One metric across two periods
Explain delta Which contributors moved a metric
Forecast metric A short-horizon projection
Marketing tools Ad spend, budget pacing, campaigns, marketing audit, lead funnel, owned channels; each appears only when its data is connected

Market-intelligence, customer-discussion and organization-dataset tools are never exposed over MCP. The platform refuses to serve the list if one of them reaches it.

If it fails#

Symptom Cause Fix
No MSO Cloud tools after a restart The bridge did not start Check the address and token in the client configuration
Every call fails after it worked Token revoked or expired Ask a super admin for a new token; revoking takes effect on the next call
Calls fail in bursts More than 30 calls a minute from one address Wait a minute and retry

Where it stops#

  • The bridge is not a hosted service and is not part of any production container; each client runs its own copy against the platform address. The platform endpoints ship with the web application. See Project status.
  • There is no write-back tool. Every tool reads.