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 what you may read is your plan’s: the API counts and limits it exactly as for any other client. A key comes from studio.debyko.com/account; the Free plan needs no card.

Status: built, not live yet. The address above, and sign-in with OAuth, start answering when the server is deployed; this page is published with it.

ChatGPT and Claude: sign in with OAuth

Add DEBYKO as a custom connector (in ChatGPT, a connector in developer mode; in claude.ai and Claude Desktop, Settings, Connectors, Add custom connector) and give it the URL, nothing more:

https://mcp.debyko.com/mcp

The 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:

• Read-only market data. The tools below, nothing else. It cannot change your account, plan, keys or Agent rules.
• 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

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/mcp

With 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

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

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

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
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 a week after the day ends; 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

Each tool is one call to one endpoint, with the arguments as the request and the API’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

The server’s initialize answer carries a paragraph of 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; every tool call counts as one request on the key, except account; call account to see the plan’s venues and limits. It also offers two resources to read, rendered from the specification and the engine, not written separately from them:

• docs://dql: the grammar of the query language of screen and where (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.

What can go wrong

• 401 with a one-line hint pointing here: the Authorization header is missing or is not a Bearer key 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). The WWW-Authenticate header names the OAuth metadata, so a client that supports OAuth starts the sign-in again by itself.
• 503 with retry-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, PLAN_VENUE_NOT_INCLUDED, DQL_UNKNOWN_FIELD and the rest. _meta carries the HTTP status and, for a 429, 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 (true for a rate limit, a database that was not reachable and an API that could not be reached; false for a call that will fail the same way, such as a query that ran past its time budget, where next says to narrow the window); and retry_after, in seconds, when it is a retry.
• A venue outside the plan is not an unknown venue: a Free key that asks for a venue its plan does not include is told PLAN_VENUE_NOT_INCLUDED, with the venues in its plan, and not DQL_UNKNOWN_VENUE.
• Counted like any call: every tool call is a /v2 request on your key, and the API counts it and limits it by your plan. 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.

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.