MCP & AI agents

Let AI assistants and agents read your workspace and run Findr searches through the Model Context Protocol (MCP). They use a workspace API key and see the same data as the Creator API.

Overview

The Creator API runs a remote MCP server. An MCP client, such as Claude Code, Cursor or VS Code, connects to it and offers its tools to the model: the workspace's Amazon earnings, product performance, brand deals and storefront, their history, and the four Findr features.

Endpoint

/workspace/v1/mcp

Transport

Streamable HTTP, stateless. Clients send JSON-RPC with POST; GET and DELETE return 405 because the server keeps no sessions or event streams.

Authentication

Authorization: Bearer vvk_... with a workspace API key. The server does not offer OAuth sign-in.

Limits

60 MCP requests per minute per key by default (120 per workspace), inside the API's 120 requests per minute per key; each tool call also counts against the budgets of the matching endpoint.

Most tools only read. The Findr tools spend the workspace's Findr credits, the same credits the Findr pages of the web app use, and say so in their descriptions and annotations (readOnlyHint: false), so clients ask before calling them.

Prerequisites

1. The API & MCP access add-on. The workspace owner buys it in the web app under Workspace settings > Billing. Without it every request fails with 403 billing.addon_required.
2. An API key. The workspace owner opens Workspace settings > API & MCP, accepts the API usage terms and creates a key named after the agent or tool that will use it. The Set up MCP button there, and the Set up MCP action of each key in the list, walk through connecting an AI app step by step; the action opens the guide with that key already filled in. The key starts with vvk_: store it in a password manager or secret store right away. If it gets lost, the owner can reveal it again later in Workspace settings > API & MCP; keys created before that was possible cannot be revealed, so create a new one instead.
3. The features the tools need. Storefront tools need the Storefront feature and each Findr tool needs its Findr feature, on the Professional plan by default, exactly as the matching web app pages. The get_workspace_info tool and GET /workspace/v1/info list every feature with whether the workspace has it.
4. An MCP client that supports remote Streamable HTTP servers with a custom Authorization header, or a stdio client with the mcp-remote bridge.

Keep the key in an environment variable, for example VIRALVUE_API_KEY, and let the client read it. The examples below assume it holds only the key, vvk_..., without Bearer. The exceptions are clients that cannot see a terminal's variables, such as the Codex app, and clients with their own secret prompt.

export VIRALVUE_API_KEY="vvk_..."

Tools

The tool descriptions state the current price. A failed search refunds its credits; a successful one cannot be undone, and repeating it charges again. When a result is too large for one tool response, the server returns the first items and sets truncated; the REST endpoints under /workspace/v1/findr return every item.

Best practices

Keys

• One key per agent or tool. Name it after the client and the machine, such as "Claude Code on Maya's laptop", so you can revoke one without breaking the others.
• Keep the exposure small. A key reads everything the workspace owner can see and can spend the workspace's Findr credits. Give keys only to clients you trust, prefer clients that run on your own machine, and do not share one key between people.
• Never paste a key into a prompt or chat, and never commit it. Keep it in an environment variable, the operating system's keychain or a secret manager, and commit only configuration that references the variable. Where a client cannot read a variable, as with the Codex app, the key sits in its configuration file: keep that file private.
• Rotate and revoke. To rotate, create a new key, update the client, then revoke the old key in Workspace settings > API & MCP. Revoke a key at once if it may have leaked; it stops working on its next request and can no longer be revealed. Revealing a key again only shows the same key, so it is no substitute for rotating one that may have leaked.

Credits and limits

• Confirm before spending credits. Keep your client's approval prompt on for the four findr_* tools, and do not add them to an always-allow list. Ask the agent to call get_findr_credits and state the cost first.
• Prefer narrow requests. Refine Findr filters rather than repeating searches, page lists with limit and offset instead of asking for everything, and ask for history over the days you need: a year of daily placements for several products can be too large for one tool result.
• Respect rate limits. By default an API key makes 60 MCP requests per minute, and each tool call counts against the same per-key and per-workspace budgets as the matching REST endpoint: Product and Campaign Findr allow 10 searches per 30 minutes, ASIN lookups 3 requests per half second and the history tools 30 calls per minute together. Limits for your workspace can differ. Send one tool call per request: JSON-RPC batches that contain tool calls are rejected with error -32600. A limited tool call returns rate_limit.exceeded with the seconds to wait.

Read-only use

• Every tool except the four findr_* tools only reads. For an agent that must never spend credits, turn those four tools off in the client; most clients let you disable single tools of a server.
• No tool writes data, sends messages, buys credits or changes settings.
• Titles, notes and list descriptions come from Amazon, brands and your team. Treat them as data, not instructions, and review what an agent does with them.
• Tool results are your private business data. Check where your client sends them before connecting it.

Set up a client

Client configuration formats change often. Each example links the client's documentation it follows; check it if a step does not match your version. All examples name the server viralvue.

In the web app, Workspace settings > API & MCP, each key in the list has a Set up MCP action. It opens a step-by-step guide for the apps below, in the same order, with that key already filled in. The guide puts the key straight into an app's own settings where the examples below use an environment variable. This page is the reference for the formats.

• ClaudeRecommendedDesktop app, claude.ai and mobile
• Codex appRecommendedDesktop app (OpenAI)
• Codex CLITerminal
• Gemini CLITerminal
• Claude CodeTerminal
• CursorCode editor
• VS Code (Copilot)Code editor
• WindsurfCode editor (Devin Desktop)
• Other appAny app that supports MCP
• stdio-only clientsmcp-remote

Claude

Custom connectors run from Anthropic's cloud and work in Claude Desktop, claude.ai and the mobile apps. Sending an API key needs the connector's Request headers option, which is in beta and not yet offered to every organization:

1. Open Customize > Connectors and choose Add custom connector. On Team and Enterprise plans an owner adds it under Organization settings > Connectors, and every member then shares that one key.
2. Name the connector Viral Vue, enter the endpoint /workspace/v1/mcp and set authentication to No sign-in.
3. Under Request headers, add authorization with the value Bearer vvk_..., including the word Bearer, and mark it required.

If your account has no Request headers option, connect Claude Desktop through the local mcp-remote bridge instead. Open Settings > Developer > Edit Config and add the server to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "viralvue": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "/workspace/v1/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${VIRALVUE_AUTH_HEADER}"
      ],
      "env": { "VIRALVUE_AUTH_HEADER": "Bearer vvk_..." }
    }
  }
}

This file holds the key in plain text; keep it private. The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

Codex app

The Codex app is OpenAI's desktop app. Apps you start from the desktop do not see the environment variables of a terminal, so unlike the Codex CLI it cannot read the key from a variable: the key goes into the app's configuration file, ~/.codex/config.toml (the .codex folder in your user folder on Windows). The Codex app and the Codex CLI share this file.

First open the file. In a terminal, run the line for your computer. It opens the file in a text editor and creates it if it does not exist; on Windows, click Yes if Notepad asks to create it:

mkdir -p ~/.codex && touch ~/.codex/config.toml && open -e ~/.codex/config.toml

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null; notepad "$HOME\.codex\config.toml"

mkdir -p ~/.codex && nano ~/.codex/config.toml

Add this at the end of the file, with your key instead of vvk_..., and save it:

[mcp_servers.viralvue]
url = "/workspace/v1/mcp"
http_headers = { Authorization = "Bearer vvk_..." }

If the file already has a [mcp_servers.viralvue] block, for example from the Codex CLI steps, replace it with this one: two blocks with the same name break the file. This block also works for the Codex CLI, so you do not need both.

Quit the Codex app completely and open it again. Open Settings > MCP servers: viralvue should be in the list and switched on. In a Codex chat, type /mcp to see the connected servers.

Codex CLI

The Codex CLI and the IDE extension share ~/.codex/config.toml. Codex sends an environment variable as a bearer token, so the key never goes into the file. For the Codex app, which does not see the variables of a terminal, follow its steps instead.

Save the key in a variable, then close the terminal and open a new one. If you also use the IDE extension, restart your editor so it sees the key:

echo 'export VIRALVUE_API_KEY="vvk_..."' >> ~/.zshrc

setx VIRALVUE_API_KEY "vvk_..."

echo 'export VIRALVUE_API_KEY="vvk_..."' >> ~/.bashrc

Then add the server in the new terminal:

codex mcp add viralvue \
  --url /workspace/v1/mcp \
  --bearer-token-env-var VIRALVUE_API_KEY

This writes the same block to the configuration file; you can also add it by hand:

[mcp_servers.viralvue]
url = "/workspace/v1/mcp"
bearer_token_env_var = "VIRALVUE_API_KEY"

Run codex mcp list to check it: viralvue should be in the list. Then start codex and type /mcp to see the connected servers.

Gemini CLI

Add the server to ~/.gemini/settings.json for your user, or .gemini/settings.json in a project. httpUrl selects Streamable HTTP:

{
  "mcpServers": {
    "viralvue": {
      "httpUrl": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${VIRALVUE_API_KEY}" }
    }
  }
}

Or add it from the terminal; the single quotes keep the variable reference in the file:

gemini mcp add --transport http --scope user \
  --header 'Authorization: Bearer ${VIRALVUE_API_KEY}' \
  viralvue /workspace/v1/mcp

Run /mcp in a Gemini CLI session to check it.

Claude Code

Add the server for all your projects. The shell expands $VIRALVUE_API_KEY, so the key is stored in your user configuration, ~/.claude.json:

claude mcp add --transport http --scope user viralvue \
  /workspace/v1/mcp \
  --header "Authorization: Bearer $VIRALVUE_API_KEY"

To share the server with a project, commit a .mcp.json at the repository root that reads the key from each developer's environment. Never use --scope project with the command above: it would write the key itself into the shared file.

{
  "mcpServers": {
    "viralvue": {
      "type": "http",
      "url": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${VIRALVUE_API_KEY}" }
    }
  }
}

Run claude mcp list to check the connection, then /mcp inside Claude Code to see the tools.

Cursor

Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project. Cursor reads the key from your environment, so start Cursor from an environment that has VIRALVUE_API_KEY:

{
  "mcpServers": {
    "viralvue": {
      "url": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:VIRALVUE_API_KEY}" }
    }
  }
}

The Cursor CLI reads the same file; check it with agent mcp list.

VS Code (Copilot)

Add the server to .vscode/mcp.json in a workspace, or run MCP: Open User Configuration for every workspace. With an input, VS Code asks for the key the first time the server starts and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "viralvue-api-key",
      "description": "Viral Vue API key",
      "password": true
    }
  ],
  "servers": {
    "viralvue": {
      "type": "http",
      "url": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:viralvue-api-key}" }
    }
  }
}

Open the Chat view in Agent mode and pick the tools in the tools menu. Sessions that run in the Copilot harness do not receive ${input:...} secrets; for those, use the portable .mcp.json at the workspace root, which reads an environment variable:

{
  "mcpServers": {
    "viralvue": {
      "type": "http",
      "url": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${VIRALVUE_API_KEY}" }
    }
  }
}

Windsurf (Devin Desktop)

Windsurf is now Devin Desktop. For the Cascade agent, open the MCP configuration file from the app's MCP settings and add the server. ${env:...} reads the key from your environment:

{
  "mcpServers": {
    "viralvue": {
      "serverUrl": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:VIRALVUE_API_KEY}" }
    }
  }
}

Conversations on the Devin Local agent use the Devin CLI configuration instead:

devin mcp add -s user viralvue /workspace/v1/mcp \
  -H "Authorization: Bearer $VIRALVUE_API_KEY"

Other app

Many clients accept this shape. Some name the URL field serverUrl or httpUrl, omit type, or expand variables as ${env:NAME}; check your client's documentation.

{
  "mcpServers": {
    "viralvue": {
      "type": "http",
      "url": "/workspace/v1/mcp",
      "headers": { "Authorization": "Bearer ${VIRALVUE_API_KEY}" }
    }
  }
}

stdio-only clients (mcp-remote)

Clients that only start local stdio servers can reach the endpoint through the open-source mcp-remote bridge, which runs with Node.js on your machine. Keep the whole header value in an environment variable and leave no spaces in the arguments: some clients split arguments at spaces. Use --transport http-only, because the server has no SSE fallback.

{
  "mcpServers": {
    "viralvue": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "/workspace/v1/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${VIRALVUE_AUTH_HEADER}"
      ],
      "env": { "VIRALVUE_AUTH_HEADER": "Bearer vvk_..." }
    }
  }
}

mcp-remote expands ${VIRALVUE_AUTH_HEADER} itself. With --header-file it reads the header from a file instead, which keeps the key out of the client's configuration.

Troubleshooting

Test the key and the endpoint without a client. A working setup answers with the tool list:

curl /workspace/v1/mcp \
  -H "Authorization: Bearer $VIRALVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'