Connecting AI agents

MCP is an open way to give a model access to a data source: the agent sees a list of tools and calls them itself when an answer needs them. Our server is a thin wrapper over the same machine interface described on the developers page: it adds no data of its own and no load of its own, and it works with your reader key.

Installation

pip install tradealmanac-mcp

# check the key before any editor
TRADEALMANAC_API_KEY=afk_… tradealmanac-mcp --check

npx -y @tradealmanac/mcp-server --tools

The two implementations are equivalent: same tools, same limits, same answers, one shared manifest. Pick whichever runtime is already on your machine. Neither has dependencies — the server runs inside your editor's environment, and there is no reason to drag third-party packages in there.

Claude Desktop

{
  "mcpServers": {
    "tradealmanac": {
      "command": "tradealmanac-mcp",
      "env": { "TRADEALMANAC_API_KEY": "afk_…" }
    }
  }
}

The file lives in the application settings, under «Developer». Restart Claude Desktop after editing it — the tool list is read once at start-up.

Cursor

{
  "mcpServers": {
    "tradealmanac": {
      "command": "npx",
      "args": ["-y", "@tradealmanac/mcp-server"],
      "env": { "TRADEALMANAC_API_KEY": "afk_…" }
    }
  }
}

A config inside a project applies to that project only; the one in your home directory applies everywhere. Other agent editors understand the same block — the MCP configuration format is shared.

Claude Code

claude mcp add tradealmanac \
  --env TRADEALMANAC_API_KEY=afk_… -- tradealmanac-mcp

By address, no install

The same server answers at an address — for clients that connect a server by link: paste it into the MCP server address field. The tools, ceilings and answers are the same as in the packages. The key goes in the Authorization header; without a key the indicators, calendar effects and rankings answer, the other tools need a key — the sandbox one will do.

https://tradealmanac.com/mcp

claude mcp add --transport http tradealmanac https://tradealmanac.com/mcp \
  --header "Authorization: Bearer afk_…"

Tool descriptions served at the address are English by default too; add ?lang=ru to the address to get them in Russian.

Would rather not set it up by hand? The “Connect to your AI assistant” page has a button for Claude, ChatGPT, Cursor and other clients.

Want to use the server next to a broker’s? The “Recipes” page shows how to connect both, with three ready-made requests.

The tools that need a key accept either a key or sign-in through consent in the app. A client that supports sign-in (Claude, ChatGPT) opens the consent page on this site by itself; then no key is needed in the client settings. The access you grant is listed and can be revoked in Account → Connected agents.

The server may also offer personal tools — watchlists and alerts. They need separate permissions, “Watchlists” and “Alerts”, which you see and tick on the consent page; if the server does not offer them, the consent page shows no such permissions. What you did not allow, the agent cannot touch, and a key alone never opens personal data.

With its own permission, “Paper portfolio”, the server may also let the agent read your practice account and place practice orders on it; the money is virtual and no real order is sent to a broker or an exchange.

Server language

Tool titles and descriptions, the server instructions and error messages are English by default. A second language is built in: add the variable from the block below to the server environment, and the same texts come in the language of the ru edition. Tool names, argument names and the fields of an answer do not depend on the language.

"env": {
  "TRADEALMANAC_API_KEY": "afk_…",
  "TRADEALMANAC_MCP_LANG": "ru"
}

The key

Keys are issued free of charge in your account, under «API». There is a sandbox key for a first try: it consumes no quota, but it answers with a daily snapshot, so it will not show you fresh numbers.

TRADEALMANAC_API_KEY=afk_sandbox_tradealmanac_demo tradealmanac-mcp --check

Four scenarios

• Build a screen — «Find oil and gas names with a dividend yield above 8 % and a P/E below 6, show them as a table.» The agent will fetch the sector codes, check the units of each field, and run the screener itself.
• Compare dividends — «Compare the dividend history of Sberbank and Lukoil over five years and tell me whose payouts are more regular.» The answer carries announcement statuses: a forecast must be called a forecast.
• Export the calendar — «Export the upcoming record dates through the end of the year to CSV.» The calendar is paged by cursor, and saving the file is done by the editor itself.
• Ask about sentiment and seasonality — «What is the mood on the Russian and US markets right now, and how does the MOEX index usually behave in January?» Indicators are read by one shared tool by identifier, and a calendar effect comes with its number of observations and significance — past statistics must not be passed off as a forecast.

What the agent will not get here

MOEX quotes, candles and the instrument reference are not part of the contract — not in real time, not delayed, not from storage; neither is global market data. A «share price» tool will not appear in this server, and that is a licensing boundary rather than an omission. The server tells the model so on the very first connection: an agent with nothing to answer must say so, not borrow a number from elsewhere and sign our name under it.

Limits

The quota is your own — the key's quota: 60 requests a minute and 1 000 a day on a free key. When it runs out, a 429 arrives with the number of seconds to wait, and the server does not retry on its own: retrying into an exhausted quota turns a ceiling into a storm. Tool answers are capped in size; if a selection is longer, the answer carries a note saying how many records were hidden — part of a selection is never passed off as all of it.

Questions about access and requests for higher limits go through contacts.