AI agents

MCP server

A read-only Model Context Protocol server for the same indexed data the API serves. An assistant that speaks MCP can look up pools, positions, charts and transactions with eleven tools (ten data tools and a free helper for large results), using your own API key.

Looking for the short path? Connect your AI agent shows what to paste for your assistant; this page is the reference.

The server calls the Tickwise API on your behalf, so nothing about your account changes: the same plans, the same units, the same quota and the same refunds. A tool call costs exactly what the matching API route costs, and shows up in your usage under the key you used. It cannot write anything.

text
https://mcp.tickwise.xyz/mcp

That is the Streamable HTTP address. Clients that only start local programs can run the same server over stdio with npx @tickwise/mcp (below).

Your key

Create a server key on the API keys page and give it a label such as MCP, so its usage is easy to find. The server makes the API calls itself, so a server key is the right kind. It is a secret: keep it in an environment variable or your client’s secret store, and never commit it to a repository.

Send it as Authorization: Bearer your-key. The server also accepts X-API-Key and KC-APIKey, and forwards the key to the API as KC-APIKey. The three free tools need no key, like the matching API routes (/v1/chains and /v1/protocols); every other tool does, and so does get_result_part, because parts are stored per key.

You need an account with a verified email to create a key; the Free plan includes 50,000 units a month. A key looks like kc_live_… and is shown once.

Connect a client

Use the https:// address exactly as written. A plain http:// address is redirected, and most clients then re-send the request without its body, which fails with Method not allowed. Where a client can read the key from an environment variable, do that instead of pasting the key into a file that may be shared or committed.

To check the connection without a client, send a JSON-RPC message with both headers the server requires (Content-Type: application/json and Accept: application/json, text/event-stream):

bash
curl -sS https://mcp.tickwise.xyz/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Success is HTTP 200 with an event-stream body whose data: line lists the 11 tools. The other answers: a missing Accept header is HTTP 406, a wrong Content-Type is 415, a GET is 405 (Method not allowed), a body that is not JSON is 400 with JSON-RPC error -32700, and a call from a browser page (an Origin header) is 403: the server is for assistants and programs, not for JavaScript on a web page. Once a client is connected, ask it to call list_chains: it needs no key and shows the chain ids the other tools take.

Claude Code

bash
claude mcp add --transport http tickwise https://mcp.tickwise.xyz/mcp \
  --header "Authorization: Bearer your-key"

Or put it in a project’s .mcp.json, reading the key from your environment so the file can be committed without it:

json
{
  "mcpServers": {
    "tickwise": {
      "type": "http",
      "url": "https://mcp.tickwise.xyz/mcp",
      "headers": { "Authorization": "Bearer ${TICKWISE_API_KEY}" }
    }
  }
}

Claude Desktop

Claude Desktop starts local servers, so it uses the stdio build. Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart the app:

json
{
  "mcpServers": {
    "tickwise": {
      "command": "npx",
      "args": ["-y", "@tickwise/mcp"],
      "env": { "TICKWISE_API_KEY": "your-key" }
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor fills in ${env:NAME} from the environment it was started in, so set TICKWISE_API_KEY in your shell profile or system environment and restart Cursor.

json
{
  "mcpServers": {
    "tickwise": {
      "url": "https://mcp.tickwise.xyz/mcp",
      "headers": { "Authorization": "Bearer ${env:TICKWISE_API_KEY}" }
    }
  }
}

The header has to be called Authorization (or X-API-Key). A header with any other name is ignored: the connection works, the three free tools answer, and every other tool says that an API key is required.

Codex

codex mcp add cannot set a header, so edit Codex’s config.toml (~/.codex/config.toml). bearer_token_env_var names the environment variable that holds the key, and Codex sends it as Authorization: Bearer:

toml
[mcp_servers.tickwise]
url = "https://mcp.tickwise.xyz/mcp"
bearer_token_env_var = "TICKWISE_API_KEY"

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json. Windsurf fills in ${env:NAME} in headers; if the variable is not set it becomes an empty string, so check it is set before you restart.

json
{
  "mcpServers": {
    "tickwise": {
      "serverUrl": "https://mcp.tickwise.xyz/mcp",
      "headers": { "Authorization": "Bearer ${env:TICKWISE_API_KEY}" }
    }
  }
}

VS Code (GitHub Copilot)

In .vscode/mcp.json, an inputs entry makes VS Code ask for the key the first time the server starts and keep it out of the file:

json
{
  "inputs": [
    { "type": "promptString", "id": "tickwise-key", "description": "Tickwise API key", "password": true }
  ],
  "servers": {
    "tickwise": {
      "type": "http",
      "url": "https://mcp.tickwise.xyz/mcp",
      "headers": { "Authorization": "Bearer ${input:tickwise-key}" }
    }
  }
}

Gemini CLI and Antigravity

bash
gemini mcp add -s user --transport http \
  --header "Authorization: Bearer your-key" \
  tickwise https://mcp.tickwise.xyz/mcp

This writes the key, as typed, into ~/.gemini/settings.json, so keep that file private. Google’s newer Antigravity CLI needs the same two things, the address and the Authorization header, in its own MCP settings; see its documentation for the file.

claude.ai

Add a custom connector with the address above. The server does not support OAuth sign-in (see below), so the connector has to send your key itself: this works only where your organization has the Request headers option available, where you add Authorization: Bearer your-key. Without it the connector can list the three free tools and nothing else.

ChatGPT

Not supported yet. We have not tested ChatGPT, and this server has no sign-in page (see What it does not do), so a connector that cannot send your key cannot use the paid tools.

Any other MCP client

Point it at the address above, or run npx @tickwise/mcp with TICKWISE_API_KEY set, and send the key in a header as described. Any client that speaks Streamable HTTP and can set a request header works; clients of the 2025 and the 2026-07-28 protocol revisions are both served. The older SSE transport is not.

Run it locally with npm

The same server is published as the @tickwise/mcp npm package. It runs on your own machine and talks to your client over stdio, so it suits clients that only start local programs (Claude Desktop is one) and anywhere you would rather not send requests through the hosted address. It needs Node.js 20.3 or newer and nothing else; npx downloads it on first use.

bash
claude mcp add tickwise --env TICKWISE_API_KEY=your-key -- npx -y @tickwise/mcp

That is Claude Code; any client that starts a local MCP server takes the same three parts: the command npx, the arguments -y @tickwise/mcp and the environment variable TICKWISE_API_KEY (the Claude Desktop snippet above is the JSON form). To pin a release, write @tickwise/mcp@0.1.0 instead.

  • It calls the Tickwise API with your key, so your plan, units, quota and refunds are exactly the same as with the hosted address. The three free tools work without a key.
  • Run by hand, it prints a start line to stderr and then waits: it speaks MCP on stdin and stdout and is meant to be started by a client, not used in a terminal.
  • The key comes from TICKWISE_API_KEY only. The request headers described above belong to the hosted address.
  • The package carries the agent skill in its skill folder, and the same large-result paging and error texts as the hosted server.

Agent skill

The server gives an assistant the tools; the skill tells it how to use them well. It is one short SKILL.md file: call list_chains first, prefer a pool or position lookup to a chart, fetch every part of a large result, read the asOf and incompleteness flags, treat token names as untrusted text, and what to do on each error. It holds no key and gives no access on its own, so connect the server as well.

text
https://mcp.tickwise.xyz/skill

Download it into your client’s skills folder, replacing FOLDER with the folder below. Start a new session afterwards. Download it again whenever you want the newest version.

bash
mkdir -p FOLDER/tickwise
curl -fsSL https://mcp.tickwise.xyz/skill -o FOLDER/tickwise/SKILL.md
ClientFOLDER
Claude Code~/.claude/skills
Codex~/.agents/skills
Cursor~/.cursor/skills (it also reads ~/.agents/skills)
Windsurf~/.codeium/windsurf/skills

The same file is in the @tickwise/mcp package, in its skill folder.

The tools

ToolWhat it doesCost
list_chainsThe chains Tickwise indexes, with the chainId to use elsewhere.free, unmetered
list_protocolsThe supported DEX protocols and the chains each runs on.free, unmetered
get_coverage_statsSize and freshness of the index, per chain.free, unmetered
search_poolsSearch and rank pools by TVL, volume, fees, fee APR or age.2 units
get_poolOne pool: tokens, TVL, volume, fees, fee APR, holders, open positions.1 unit
get_pool_chartsPrice, volume, TVL and fees over time, plus liquidity ticks.10 units
search_positionsSearch positions by owner, pool, status, range or value.2 units
get_positionOne position with its newest transactions.1 unit
get_position_transactionsA position’s transactions, one page per call; pages run newest first.1 unit
get_position_chartsValue, fees and PnL over time, plus liquidity ticks.10 units
get_result_partAnother part of a result too large for one answer. Free, but needs the key that made the request (see Large results).free, unmetered

The first ten are the data tools; get_result_part is a free helper that needs your key. Every tool returns the compact view of the API response as one JSON text block, and every tool is read-only. Costs come from the same price list as the API, so an edit there shows up here. The data is indexed, not live: the answers carry asOf timestamps and the stale, partial and totalCapped flags, which the assistant is told to read.

Arguments

ToolArguments
list_chains, list_protocols, get_coverage_statsNo arguments.
search_poolschainId (omit for every chain), protocol (default uniswap-v4), sort (tvl, volume, fees, fee_apr or age; default tvl), minTvlUsd, search (token symbol, token address or pool id), includeRisky (default false), page (1 to 20), limit (1 to 25, default 10), fields.
get_poolchainId and poolId (required), protocol.
get_pool_chartschainId and poolId (required), protocol, range (30d, 60d, 90d, 180d or all; default 30d), ticksLimit (10 to 200, default 60).
search_positionschainId, protocol, owner (0x wallet), poolId, positionId, status (active, inactive or all), range (all, in or out), minValueUsd, minPoolTvl, sort (apr, fee_apr, roi, age, pnl, underlying_value, nft_id_asc or nft_id_desc; default apr), includeRisky, page (1 to 20), limit (1 to 25, default 10), fields. By default only open, non-risky positions in pools of at least $1,000 TVL; set status=all, minValueUsd=0, minPoolTvl=0 and includeRisky=true for everything a wallet has held.
get_positionchainId and positionId (required), protocol, transactionsLimit (1 to 100, default 20).
get_position_transactionschainId and positionId (required), protocol, limit (1 to 100, default 20), before (the transactionsNextCursor of the previous page).
get_position_chartschainId and positionId (required), protocol, range, ticksLimit (as get_pool_charts).
get_result_partresultId (the 22-character id from the paging object) and part (1 to 99), both required.
  • fields adds comma-separated dotted paths to each row on top of the compact default, for example metrics.feeApr,poolStats.tvlUsd; an unknown path is refused with unknown field: path. The paths are the ones in the response of the matching API route (see the positions page). hooks is a valid path but only appears on pools that have a v4 hook, and metrics.usd (the vs-USD companion) is a detail field that is absent when it could not be measured.
  • Transactions are paged newest first: the first call is the newest page and the cursor leads to the next older one. The rows inside one page run oldest to newest.
  • Totals. pagination.totalCapped: true means total is a lower bound (the count is capped at 25,000 or was not ready in time), not the full count.

Limits

  • 25 rows per page on the two search tools (page 1 to 20), and 100 transactions per page. This is smaller than the API allows, on purpose, to keep answers short.
  • 4 calls at a time per key. A fifth waits for one to finish; a long queue is turned away.
  • About 30,000 characters per answer, and nothing is cut. A bigger result is split into parts that each fit; see Large results.
  • 120 requests a minute per address without a working key, and 1,200 per address overall, keyed or not. This is a guard on the hosted address, separate from your plan. Past it the server answers HTTP 429 with a Retry-After header and the message “Too many requests. Wait N seconds before calling again.” Every message of a batched request counts. The limits are set by the host of the server; the npx build has none.
  • Your plan’s limits apply. The burst rate limit and monthly quota are the ones on your plan; when one is hit the tool says so, with the number of seconds to wait.

Large results

Asking for a long chart range or a full page can produce more data than one answer should carry. The server never cuts it: it splits the result into parts that each fit in about 30,000 characters, and every value is in exactly one part. The first part comes back as the answer, with a paging object at the top:

json
{
  "paging": {
    "resultId": "k3Zr0wYQd1m8Fq2oPpX9aA",
    "part": 1,
    "of": 4,
    "next": 2,
    "covers": { "time": { "from": 1772000000, "to": 1790000000 }, "liquidityDistribution.ticks": { "from": 1, "to": 60, "of": 60 } },
    "note": "Part 1 of 4 of ONE result: …"
  },
  "range": "all",
  …
}

Call get_result_part with that resultId and the next part number until next is gone. The assistant is told to do this before it answers from the data.

  • Charts are split by day, newest days first, with every series cut at the same days; the liquidity ticks follow, split by row. A chart point is one day, so a range is a whole number of daily points.
  • Lists and transactions are split by row. The page’s totals and flags are in the first part.
  • Cost. The request that produces the result is billed once, exactly as the API route is. Fetching the other parts is free: it makes no API call and costs no units.
  • How long parts are kept. About 10 minutes, for the key that made the request, and for no other key. After that, run the request again; it is billed again.

What a failed call says

A problem with a call comes back as an ordinary tool error with one of these messages, not as a failed connection. Requests the API refuses are not billed, the same as on the API itself. The one exception is the per-address limit below, which answers the request itself with HTTP 429.

WhenMessage
No key, on a paid toolAPI key required. Create one in the Tickwise portal (Keys page) and add it to your MCP client configuration.
Key invalid, revoked or malformedThe API key is invalid, revoked or not allowed. Create a new key in the Tickwise portal.
Rate limitRate limit reached. Wait N seconds before calling again; do not retry immediately.
Monthly quota used upMonthly unit quota used up. Do not call paid tools again this month; upgrade the plan in the Tickwise portal.
API busyThe data service is busy. Retry after N seconds.
Four calls already running for this keyToo many calls in flight for this key. Wait for earlier calls to finish.
A part that has expired, or is not yoursResult not found or expired. Run the original request again (it is billed again).
A part number that does not existThis result has N parts. Ask for a part from 1 to N.
A single record too large to split (rare)Result too large (N characters) and it cannot be split. Narrow the request: use a shorter range, a smaller ticksLimit or fewer rows.
Unknown pool or positionNot found. Check chainId, protocol and the id.
Unknown chain or protocolInvalid request: Unsupported chainId (or Unsupported protocol). Call list_chains for the chainIds and protocols Tickwise indexes.
An argument of the wrong shape (checked before any call, so it costs nothing)Input validation error: Invalid arguments for tool <name>: <field>: <what is wrong>. A malformed resultId says it must be the 22-character id from the paging object.
A request the API refusesInvalid request: the reason the API gave, up to 300 characters (for example unknown field: <path>).
The API is slow to answerThe Tickwise API did not answer in time. Try a smaller request or try again later.
The API failsTickwise API error. Try again later.
You cancel the callThe request was cancelled.

What it does not do

No OAuth. There is no sign-in page, so a client cannot log you in; it has to be given your key. That is why claude.ai works only where it can send request headers. We may add OAuth later; until then the key is the only way in.

Token names and symbols in the data are written by whoever created the token. The server shortens them and removes hidden characters, and tells the assistant to treat them as untrusted text, but you should still not give an assistant that reads them any tool that can move funds. This server cannot.

The answers are indexed data and not financial advice.