> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Connect Claude Code, Cursor or Codex to BeatAPI social data

> Configure the remote MCP in each client, then verify its tools and collect a traceable first batch.

Add BeatAPI as a remote MCP server named `beatapi` in Claude Code, Cursor or Codex, with `BEATAPI_API_KEY` supplied from the environment. Public lookups need only the BeatAPI key, not Xiaohongshu cookies. After setup, the agent has three tools: `capabilities_search` finds an action, `capabilities_inspect` shows the action's inputs, price and readiness, and `capabilities_run` executes the action. As a first task, ask the agent to search one Xiaohongshu page for “coffee machine descaling” and shortlist notes worth opening. Search Douyin when you need a video demonstration, and fetch a WeChat article's text when you have the article URL.

## Configure your client

Provide `BEATAPI_API_KEY` through the client process environment or the client's credential settings; the examples below reference the variable name only. A desktop app may start outside your shell environment, so restart Cursor after making `BEATAPI_API_KEY` available to the Cursor process. If an MCP configuration file already exists, merge the `beatapi` entry into the existing file.

### Claude Code

Add the following to your project's `.mcp.json`. In a project session, open `/mcp` to see the `beatapi` connection and tools. If Claude Code asks for project approval, verify the server address before approving.

```json
{
  "mcpServers": {
    "beatapi": {
      "type": "http",
      "url": "https://beatapi.io/mcp",
      "headers": {"Authorization": "Bearer ${BEATAPI_API_KEY}"}
    }
  }
}
```

### Cursor

Use `.cursor/mcp.json` for one project or `~/.cursor/mcp.json` for your account. In Cursor's MCP settings, confirm that the `beatapi` server is enabled and that the `beatapi` tools are available in Agent.

```json
{
  "mcpServers": {
    "beatapi": {
      "url": "https://beatapi.io/mcp",
      "headers": {"Authorization": "Bearer ${env:BEATAPI_API_KEY}"}
    }
  }
}
```

### Codex CLI

Add the block below to `~/.codex/config.toml`. Start a new Codex session and use `/mcp` to inspect the loaded tools.

```toml
[mcp_servers.beatapi]
url = "https://beatapi.io/mcp"
bearer_token_env_var = "BEATAPI_API_KEY"
```

## Collect a first batch

1. **Check the connection.** Look for `capabilities_search`, `capabilities_inspect` and `capabilities_run` in the tool list. Ask the agent to find Xiaohongshu keyword search with `capabilities_search`, then pass the exact returned `reference` to `capabilities_inspect` to see the required inputs, price and readiness. The connection check ends at this step.
2. **Search one page.** When you are ready to gather evidence, send one keyword and search one page. When the response is a preview, record the request ID, `items_path` and the observed scope of the preview. Keep the saved response. Select one relevant note with a source before deciding whether to fetch the note's comments.
3. **Add other platforms.** Use [Douyin keyword search](/guides/douyin-python-research) for videos. With a verified WeChat account, start with the account's [article list](/guides/wechat-incremental-articles); with one article URL, fetch the article body if needed. For each source, keep the action, object ID, original link and material type.

Example first prompt:

> Find Xiaohongshu keyword search and show the inputs and price for one page. Once I choose the keyword, fetch one page. Give me the actual candidates and sources, then flag any that merit reading the comments. Label excerpts as excerpts.

For recurring research, save your review criteria and output columns in a task Skill for your client, and use the [BeatAPI Skill](https://beatapi.io/skill.md) for tool instructions. Before querying again, reuse saved results that already contain the evidence you need.

## How do you know the first lookup gave you something usable?

* **The tool and price are visible.** When the agent lists the required inputs and price for Xiaohongshu keyword search, the tool entry point works. Then supply the term you want to search.
* **You have a lead you can check.** When a preview shows a note titled “My machine still smells after descaling,” ask the agent to put the returned note ID, request ID and material type (“search excerpt”) on the same row. The row lets you trace the source or fetch the selected note later.
* **Only the first few items are visible.** Compare `items_total` with the number of items shown. To see other items the lookup already returned, read the saved result with the same `reference` and `request_id`, following the response's `next` instructions when present. Request a new page only when you need additional results.

[BeatAPI preview and result retrieval](https://beatapi.io/skill-refs/run.md)

For example, the preview shows three items and `items_total` is 20. To pick a second example, open the saved result and choose from the 20 returned notes by note ID. If the 20 notes do not cover the machine model you need, request the next platform page or run a more specific search. In the brief, record the batch you reviewed and the note you selected.

## Troubleshoot the connection and results

| What you see                  | Check                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| No server or tools            | Active config location, process environment, project approval and remote HTTP transport |
| A 401 response                | Whether the client sends the Bearer header and whether the key is active                |
| Tools appear but a call fails | The tool error, request ID and inspected input contract                                 |
| A trimmed list or excerpt     | The preview scope and the saved result before deciding to fetch another page            |

Extra pages, note details and comment requests are billed as separate requests; see [BeatAPI pricing](https://beatapi.io/pricing). The [note search](/guides/xiaohongshu-notes-research) and [comment research](/guides/xiaohongshu-note-comments) guides give the response paths and paging.

[BeatAPI setup](https://beatapi.io/skill-refs/setup.md) · [Claude Code MCP](https://code.claude.com/docs/en/mcp) · [Cursor MCP](https://cursor.com/docs/mcp)