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.
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-serveris a Node program in the repository, started withpnpm --filter @yng/mcp-server startfrom a checkout. It readsUCIP_API_URLandUCIP_API_TOKENfrom 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#
- A super admin mints the token as above.
- Add the bridge to the client's MCP configuration as a stdio server, with the two environment variables, and restart the client.
- 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.