# Use okdata in Coze: an MCP plugin or an API plugin

> Turn okdata into a Coze plugin, either MCP-based or built on the HTTP API, so your bots and workflows can read Xiaohongshu, Douyin and Weibo data.

Canonical page: https://okdata.online/integrations/coze/

With this in place, a bot you build in Coze can look things up on social platforms while it talks. Take a "Xiaohongshu topic scout" for a marketing team: someone asks "what are this week's most-liked Xiaohongshu notes about quick morning makeup actually saying?", and the bot searches two pages of popular notes, sums up what they share and links the best examples. The data is fetched live, not recalled.

Coze runs two separate sites: 扣子 at coze.cn for mainland China and Coze at coze.com. This page follows coze.cn, where both ways below are documented, with notes for coze.com at the end. On coze.cn, plugins, low-code bots and workflows now live in the **扣子开发平台** (the developer platform, reached from the 扣子编程 home page via **回到旧版**, "back to the old version").

## Before you start

- A Coze account with access to the developer platform.
- An API key from okdata, starting with `okd_`. New keys come with $0.10 of credit. The [quickstart](/docs/quickstart/) explains how to get one.

Our other pages keep the key in the `OKDATA_API_KEY` environment variable. Coze runs in the cloud, so the key goes into the plugin's authorization settings and Coze stores it. Every conversation with a bot that uses the plugin spends your balance, whoever is talking to it. Think about that before you publish the bot to the Coze store, WeChat or Feishu.

## Way 1: an MCP plugin (recommended)

You create it once, the four tools sync in by themselves, and the bot can find endpoints and prices on its own.

1. Pick the workspace at the top, click **资源库** (Library) on the left, then **+资源 > 插件** (+ Resource > Plugin) at the top right.
2. Name it `okdata`, set **类型** (type) to **MCP**, and enter `https://api.okdata.online/mcp` as the **插件 URL** (plugin URL).
3. For authorization choose **Service > Service token / API key**:
   - **位置** (location): Header
   - **Parameter name**: `Authorization`
   - **Service token / API key**: `Bearer okd_...`, the word `Bearer`, a space, then your full key
4. Click **确认** (confirm). Coze syncs the server's tools: `find`, `describe`, `call` and `account`.
5. Test-run `find` with `query` set to "xiaohongshu search". A list of endpoints back means the connection works, for free. Then run `account`; a balance means the key works.
6. Click **发布** (publish). Bots and workflows can only add a plugin after it is published.

Coze's documentation doesn't say which MCP transport it uses; okdata speaks Streamable HTTP. If no tools appear in step 4, use way 2.

## Way 2: a plugin on the HTTP API

Better when a workflow always calls the same endpoint, such as one Xiaohongshu search every morning.

1. In the Library choose **+资源 > 插件** again, and pick **云侧插件-基于已有服务创建** (cloud plugin based on an existing service).
2. Set the plugin URL to `https://api.okdata.online`, and authorization exactly as in way 1.
3. Add a tool: path `/v1/xiaohongshu/notes/search`, method GET, one input parameter `query` (string, required, sent in the query string), plus `sort` if you want it.
4. Debug it once so Coze can build the output parameters from a real response, then publish.

You can also use **导入** (Import) and give `https://okdata.online/openapi.json` under **URL 和原始数据** (URL and raw data). Two caveats: Coze's docs only show examples for OpenAPI 3.0, Swagger and Postman, and our file is OpenAPI 3.1, so the import may fail; and if it works, the thirty-odd tools arrive disabled and untested, to be switched on one by one. For a couple of endpoints, building them by hand is quicker.

## A first prompt to try

Add the plugin to a bot and ask in the preview:

```text
What are this week's most-liked Xiaohongshu notes about "早八妆容" saying?
Search two pages sorted by popularity, give me three things they have in
common with one example link each, and tell me what it cost.
```

It helps to add a line to the bot's persona: "State the cost before calling okdata, and make at most two paid calls per question."

## What it costs

`find`, `describe` and `account` are free; only `call` is billed. [Xiaohongshu note search](/apis/xiaohongshu/notes/search/) is $0.02 a page, so two pages cost $0.04. A Weibo hot list is $0.002, a Douyin one $0.002. Failed calls are free. The bot's language model is metered by Coze, separately from okdata.

## When something goes wrong

- **401 `unauthorized`.** The key is missing or malformed. Check that the parameter name is `Authorization` and the value is `Bearer ` plus the full key. If that still fails, try the key alone, without `Bearer `, in case Coze adds the prefix itself.
- **402 `insufficient_balance`.** Not enough balance for the call. Nothing was charged. Top up and try again; prices are on the [pricing page](/pricing/).
- **429 `rate_limited`.** Too many calls in a short time, usually a loop in a workflow. The response includes `retry_after_seconds`; wait that long before calling again. No charge.
- **No tools in the plugin, or the bot can't find it.** For the MCP plugin, the URL must be an https domain ending in `/mcp`. Either way, a plugin has to be **published** before bots and workflows can see it.

On coze.com the import flow and **Register for existing services** work the same way, with English labels, but its documentation does not cover MCP plugins yet, so use way 2 there.

## Read next

- [The MCP server](/mcp/): the four tools and what to tell the bot.
- [Xiaohongshu note search](/apis/xiaohongshu/notes/search/): parameters, fields and price.