Trade journal (MCP)

The trade journal server is a remote MCP (Model Context Protocol) server. It gives an AI assistant, or your own code, read-only access to one trader's journal: accounts, closed trades, fills, funding, daily equity, metrics, open positions, payouts and the account's limits. For the trader's view, see Trade journal.

#The server

It has no tool that places, changes, closes or cancels anything, and the reads behind the tools write nothing to your accounts.

#The key

The server takes a key with the journal:read scope and no other. Create one on Analytics, under Connect your AI, or in Settings by choosing Journal under Access. Creating any key needs API access and a second factor: see Authentication.

• A read or trade key is refused here with 403 insufficient_scope.
• A journal key is refused on every route of the trading API with 403 insufficient_scope.
• A live key (pk_live_) reads your real accounts. A sandbox key (pk_test_) reads the sandbox's paper account.

Everything else about a key is as on the trading API, because the same gate checks it: expiry, revocation, the IP allowlist, and the rate limits, 600 per minute for a key and 2,000 per minute across all your keys, counted together with your calls to the trading API. One HTTP request is one call. A refusal at the gate is an HTTP error in the API's envelope, { "error": "<code>", "message": "<sentence>" }, with the codes on Errors. Every response carries x-request-id and the X-RateLimit-* headers.

#Tools

Every tool is read-only. Money is in US dollars; times are ISO 8601 in UTC. from and to are a UTC day (2026-10-01) or an ISO 8601 time; a day as to means the whole day. A paged tool takes limit (1 to 500, default 100) and cursor, and answers nextCursor: pass it back as cursor for the page after, until it is null.

A tool's answer is in the result's structuredContent, and the same JSON as text in content. A tool that refuses answers isError: true with one line of text, <code>: <sentence>:

#Metrics

get_metrics computes over the closed trades of the window, with the definitions of the Analytics page: net is realized P&L less the fee, a trade at exactly zero net is flat (neither a win nor a loss), and the win rate is wins over all trades. It reads at most 5,000 trades, the newest; truncated is true when the window held more.

Drawdown, return and the risk ratios are not here: they need the marked-to-market equity curve, which the Analytics page draws.

#Payout states

status is one of pending, claimable, paid, rejected or expired. With an accountId, the answer is that account's payouts plus the profit payouts that drew from all the trader's funded accounts together, whose accountId is null.

#A sandbox key

A sandbox journal key reads the one paper account, whose id is demo; accountId can be left out. list_accounts, get_trades, get_metrics, get_open_positions and get_rules answer from it (get_rules in the shape of GET /sandbox/account). The sandbox keeps no fills, funding, daily equity or payouts, so those four answer empty lists.

#Prompts

Each takes an optional accountId.

#Call it from code

A tool call is one JSON-RPC request:

curl https://mcp.perpsfund.com \  -H "Authorization: Bearer $PERPSFUND_JOURNAL_KEY" \  -H "Content-Type: application/json" \  -H "Accept: application/json, text/event-stream" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_metrics","arguments":{"accountId":"<id>","from":"2026-10-01"}}}'

The TypeScript SDK wraps the tools as methods:

import { PerpsFundJournal } from "@perpsfund/api";
const journal = new PerpsFundJournal({ apiKey: process.env.PERPSFUND_JOURNAL_KEY! });
const [account] = await journal.accounts();const week = await journal.metrics(account.id, { from: "2026-10-05", to: "2026-10-11" });console.log(week.netPnL, week.winRatePct, week.profitFactor);
for await (const trade of journal.allTrades(account.id, { from: "2026-10-01" })) {  console.log(trade.symbol, trade.realizedPnL - (trade.fee ?? 0), trade.holdSeconds);}

A refusal throws PerpsFundError, with the code and message above.

#Connect an assistant

Connect your AI on Analytics writes the Claude Desktop block for you, with a new key in it.