MCP

How an AI assistant can build and manage your bots and read your signals through Okkana's MCP server: connecting it, the keys and scopes, the tools, and how to keep it safe.

The Model Context Protocol (MCP) is a standard way for an AI assistant to use tools that live on a server. The assistant, such as Claude Code, Cursor or VS Code, is the client. It reads the list of tools the server offers, picks one when your request needs it and sends the arguments. The server runs the tool and returns the result.

Okkana runs an MCP server for your bots and your signals. The assistant can list your bots, read the signals they produced and, if you allow it, create and change bots. Each call goes through the same checks as the API.

The server offers tools only. It has no market data, and it never places an order.

Create an API key in your profile and copy it when it appears: it's shown once and starts with okk_. The key carries the scopes you picked, and the MCP server uses the same keys as the API.

Then give your client two things: the server address, /mcp on the API's host, and an Authorization: Bearer header with the key. The transport is Streamable HTTP, so Claude Code takes --transport http. Cursor and VS Code read the same two values from their MCP configuration file; check the client's own documentation for the current file name and format.

Only an API key opens this address. A signed-in session gets a 403.

The server is built for each request with only the tools your key allows. The three catalog tools, list_metrics, list_templates and list_markets, work with any key. bots:read adds list_bots and get_bot. bots:write adds validate_rule, create_bot, update_bot, set_bot_status, duplicate_bot and delete_bot. signals:read adds list_signals and get_signal.

A tool outside the key's scopes doesn't appear in the list, so the assistant never sees it. In the profile, the Read preset gives bots:read and signals:read, and Read and write adds bots:write.

Every tool carries a hint the client can read. Eight are read-only: the three catalogs, list_bots, get_bot, list_signals, get_signal and validate_rule, which checks a definition and stores nothing. Four change your data without destroying it: create_bot, update_bot, set_bot_status and duplicate_bot. One is destructive: delete_bot removes the bot and, a little later, its signals and history. It can't be undone.

The hints are for the client, which decides what to run on its own and what to confirm with you. The description of delete_bot also tells the assistant to confirm with you first.

update_bot replaces the whole definition, so the assistant sends every field. A new market, direction, rule, cooldown or rearm starts a new revision, and past signals keep the revision that fired them.

Describe the bot in your own words. The assistant looks up the market ids and the metrics, builds the definition and calls validate_rule, which runs the same checks as create_bot and stores nothing. If it answers with errors, the assistant fixes those fields and tries again.

Then create_bot saves it, and the bot appears in your Bots page like any other. The direction is yours: the assistant has to ask whether you expect the price to rise, fall, or only want the alert, because Okkana never infers it from the rule.

A bot created without a status is a draft, and only active bots monitor the market. Activating it is a separate call, set_bot_status, that you can approve on its own.

When a definition is wrong, validate_rule answers with the problems by field path, all together: rule.conditions[1].left.timeframe is the timeframe of the second condition's left side. The assistant reads the path and the message and corrects only those fields.

Typical causes are a metric id that doesn't exist, a timeframe missing on a metric that needs one, a metric the market type doesn't have, such as funding on spot, a SHORT direction on a spot market, and an average with a lookback outside 2 to 200. Percent metrics are plain numbers: -3 means -3%.

Treat the key like a password. Start with a read key, which sees your bots and signals but can't change anything, and create a read and write key only for an assistant you want building bots. Use one key per client, so you can revoke one without touching the others. A revoked key fails immediately.

Read what the assistant is about to do before you approve a write, especially delete_bot. A new bot is a draft until someone activates it.

A key can't reach market data, your webhook, your profile or your other keys, and nothing here places an order. Each key has a limit on MCP requests per minute, 120 by default, and an account can hold 10 active keys by default.