Connect an AI agent
DEBYKO runs a remote MCP server. An agent that speaks MCP gets the data of API v2 as tools, from one URL, and there is nothing to install, no process to run and no wallet to fund. There are two ways to sign in, and every client uses one of them:
- OAuth, with your DEBYKO account: ChatGPT, Claude (claude.ai and Claude Desktop), and Claude Code and Cursor if you like. You give the client the URL and nothing else; it opens a DEBYKO page where you sign in and allow it. No key is copied anywhere.
- Your API key in a header: Claude Code, Cursor and any client that lets you set a header. The key is the credential of every request.
URL https://mcp.debyko.com/mcp (MCP Streamable HTTP)Header Authorization: Bearer <your key> (only for the key way)Either way you can read every venue and instrument. Your plan sets the history, request, DQL and stream limits; the API enforces them exactly as for any other client. A key comes from studio.debyko.com/account; the Free plan needs no card.
ChatGPT and Claude: sign in with OAuth
Section titled “ChatGPT and Claude: sign in with OAuth”Add DEBYKO as a custom connector and give it the URL, nothing more. In claude.ai and Claude Desktop: Customize → Connectors → + Add → Add custom connector → paste the URL → Continue → Add → Connect. In ChatGPT (chatgpt.com on a computer only): Plugins → + → Add custom MCP server → paste the URL → OAuth → Create; Developer mode, if it is needed, is under Settings → Apps → Advanced settings.
https://mcp.debyko.com/mcpThe client registers itself with DEBYKO and sends you to studio.debyko.com, where you sign in as you do for your account (an emailed code or link). The page shows who is asking, where it will be sent back to, your account and the plan the connection gets, and what allowing means. Choose Allow and the client is connected; choose Deny and nothing is made.
What a connection is:
- Market data, and your alerts where they are on. The data tools below only read. An account with the Agent tools on (they are being turned on account by account, and the connection’s own consent page says which you have) also lets the client link Telegram or a webhook, create, pause, edit and delete your alert rules and turn Agent on or off; without them it cannot change your Agent rules. It never changes your account, plan or keys, places orders or moves money.
- Counted on your account, held to your best plan. A connection has an API key of its own that is not in your key list and does not count against the number of keys your plan holds. Its plan is the best of your account’s plan and your live keys (a key you made, or one bought with USDC and linked to the account), so a plan bought with USDC works here too; it is re-read each time the client renews its access token, so a key that expires or is revoked, or a plan that changes, shows within an hour. Because limits apply per key, each connection has your plan’s per-key limits to itself; an account holds at most five connections.
- Short-lived. The client’s access token lasts an hour and it renews itself with a refresh token (30 days, replaced at every use; one used twice ends the connection). Nothing needs doing.
- Yours to end. Under Connected applications on your account page press End and the client stops working within a minute; closing the account ends every connection. A client can also end its own connection.
The client discovers all of this by itself (RFC 9728 and RFC 8414 documents at
https://mcp.debyko.com/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server; authorization code with PKCE S256, dynamic client registration, no client secret).
A redirect address must be https, or http on your own computer (localhost, 127.0.0.1).
Claude Code
Section titled “Claude Code”With OAuth (no key to copy): add the server, then run /mcp inside Claude Code and choose to authenticate.
claude mcp add --transport http debyko https://mcp.debyko.com/mcpWith a key:
claude mcp add --transport http debyko https://mcp.debyko.com/mcp --header "Authorization: Bearer <key>"To keep the key out of a file that is committed, put it in the environment and let the project file refer to it:
{ "mcpServers": { "debyko": { "type": "http", "url": "https://mcp.debyko.com/mcp", "headers": { "Authorization": "Bearer ${DEBYKO_API_KEY}" } } }}Cursor
Section titled “Cursor”In .cursor/mcp.json of a project, or ~/.cursor/mcp.json for every project. With only the url, Cursor signs in with OAuth; with the header it uses your key:
{ "mcpServers": { "debyko": { "url": "https://mcp.debyko.com/mcp", "headers": { "Authorization": "Bearer <key>" } } }}Claude Desktop
Section titled “Claude Desktop”Claude Desktop’s connectors take a URL and sign in with OAuth: add https://mcp.debyko.com/mcp as described above. There is nothing to install and no configuration file to edit.
What the agent gets
Section titled “What the agent gets”| tool | endpoint | what it does |
|---|---|---|
venues |
GET /v2/venues |
every venue, how many listings each has and how many are collected |
instruments |
GET /v2/instruments |
every listing, with the venue’s own symbol, tick and lot, and which layers are collected |
snapshots |
POST /v2/snapshots |
the latest reading of each layer, each value with its venue, arrival time and age |
history |
POST /v2/snapshots/history |
the same snapshot as it stood in the past (as_of), with gaps written out as gaps and their coverage |
screen |
POST /v2/screen |
a DQL query across venues |
candles |
POST /v2/candles |
completed candles; a period nobody reported is a gap, never a bar |
agent_state |
GET /v2/agent/state |
the state of the account’s Agent rules: true, false or unknown with its reason, the previous_state this key was last given, evaluated_at and effective_interval. rule_id narrows to some rules; fresh=true evaluates now and is charged against the plan’s evaluations a day |
agent_rule_get |
Account’s Agent API | the original DQL and saved settings of one rule by ID or label; reads without evaluating, including when Agent write tools are off |
anchor_proof |
GET /v2/anchors/proof |
a row of stored history and the Merkle path from it to the root of its UTC day, which is anchored on Base within 24 hours of the day’s end; verify it yourself. Needs a key |
account |
GET /v2/account |
what this key sees and what is left of it today: the plan, the venues in it, the layers, the limits, and today’s counters (requests with the remainder and by class, DQL, streams, Agent evaluations, archive files). Free: it is not counted as a request |
The Agent tools, for an account that has them: agent_channels, agent_channel_connect, agent_rule_create, agent_rule_set, agent_rule_delete, agent_set_enabled (6 in all, beside these 11). They are calls to Agent, not to the API: rules are Agent’s, and the API has no endpoint that changes one (Agent). Their arguments, annotations and refusals: MCP tools and MCP errors.
Each tool is one call to one endpoint, with the arguments as the request and the endpoint’s answer as the result, byte for byte. The server has no logic of its own and no cache,
so not_published, stale, gap, the flag derived and the coverage of a history answer reach the model exactly as the API wrote them. There is no tool for
GET /v2/stream: an open connection is not one call. The one thing added is on a failed call (below).
One vocabulary of layers. Every tool names a layer the same way: ticker, mark, funding, oi, book, stats, venue_depth (and candles, liquidation, trade beyond the snapshot).
The layers of snapshots and history are an enumeration in the tool’s schema, so a model is told the names before it guesses one.
What the model is told up front
Section titled “What the model is told up front”The server’s initialize answer carries instructions for the model: start with venues, then instruments, then snapshots; a value that is not current comes back with its
status, reason and dates and without the number (allow_stale puts it under withheld); units are published unless a call says units: base; with the Agent tools, how to make an
alert with them (concrete condition, a venue of the plan, channels first, the label, the dry run and how to turn it off), and without them, that rules are made at
agent.debyko.com after a dry run with screen; on a failed call, give the user next as it is written; venues and instruments are not counted, account
is not counted against the day, the Agent tools are not counted on the key, every other call is one request on the key. It also offers resources to read:
docs://getting-started: account, connecting a client, linking Telegram, a first rule, where firings are, how to stop, with the exact URLs and button names;docs://agent: Agent step by step (rules, channels, notifications, statuses, limits);docs://plans: every plan and its limits, read from the plan table when it is read;docs://dql: the grammar of the query language ofscreenandwhere(the specification’s own), every field and function, and ten queries that run;docs://layers: the layer names, what each holds, in which unit, and which tool takes which name.
And two prompts, for clients that show them: setup (check the account, link Telegram, a first alert) and alert (instrument, condition, delivery).
What can go wrong
Section titled “What can go wrong”401with a one-line body pointing here (codeUNAUTHENTICATED, andnext: sign in at studio.debyko.com, copy or issue a key, put it in the header or connect with OAuth): theAuthorizationheader is missing or is not aBearerkey or access token, or the API does not accept the key, or the access token is not valid any more (the connection was ended, or the token expired and the client has not renewed it). TheWWW-Authenticateheader names the OAuth metadata, so a client that supports OAuth starts the sign-in again by itself.503withretry-after: the sign-in service did not answer while an access token was being checked. The connection is fine; try again.- A tool result with
isError: the API refused the call and the body says why, with its code:RATE_LIMITED,PLAN_LIMIT,DQL_UNKNOWN_VENUE,DQL_UNKNOWN_FIELDand the rest._metacarries the HTTP status and, for a429,retry-after. Each error keeps what the API wrote (code,message,position,hint) and gains three fields for a model:next, one sentence on what to do now;retry, whether the same call can work if repeated (truefor a rate limit, a database that was not reachable and an API that could not be reached;falsefor a call that will fail the same way, such as a query that ran past its time budget, wherenextsays to narrow the window); andretry_after, in seconds, when it is a retry. - Every plan can read every venue and instrument:
DQL_UNKNOWN_VENUEmeans the platform has no such venue; a plan’s history and request limits still apply. - Counted like any call: every tool call is a
/v2request on your key, and the API counts it and limits it by your plan, exceptvenuesandinstruments(public endpoints, not counted) andaccount(not counted against the day). The server counts nothing and limits nothing. - The key is the agent’s (the key way): anything the agent can read it can repeat, and the key is in the configuration of the client you gave it to. Use a key you can replace at studio.debyko.com/account, and replace it if it was ever pasted somewhere it should not have been. With OAuth there is no key in a configuration: end the connection instead.
The server is stateless: it opens no session and keeps nothing between requests; with OAuth it asks the sign-in service about the access token on every request, and holds the connection’s key for that one request. Paying per call with x402 is a way to call the API directly; the remote server authorises with a key or an OAuth connection only. An AgentKit agent uses that same payment path, and can add three typed actions: Use DEBYKO from AgentKit.
For an agent that reads documentation rather than calls tools, an index of this site, one line per page, is at docs.debyko.com/llms.txt.