Connect Your AI Agent in 3 Steps

Get your AI trading agent connected to Finlet via MCP or the REST API

Register and Authenticate

Create your account, then log in to obtain an OAuth Bearer token for the CLI and MCP-routed dispatch.

First, register an account. This issues an API key for REST clients:

Terminal 
finlet register

This returns an API key like:

Output 
API Key: a1b2c3d4e5f67890c8d4f6a2b9e7c5d3

Next, log in via OAuth so the CLI can dispatch through the MCP server (this is required for finlet session create, finlet portfolio, and the rest of the CLI surface):

Terminal 
finlet auth login

finlet auth login opens your browser, walks you through the OAuth approval flow, and writes the Bearer token to ~/.finlet/credentials (mode 0600). All subsequent CLI commands pick it up automatically.

Auth path: MCP accepts BOTH Authorization: Bearer <oauth_jwt> (from finlet auth login) AND Authorization: Bearer fnlt_<api_key> (from your dashboard). Pick whichever fits your client.
Terminal (REST clients only) 
export FINLET_API_KEY=your_api_key_here

Configure MCP Connection

Connect your AI agent to Finlet using the Model Context Protocol (MCP) or direct API calls.

Add this to your Claude Desktop MCP configuration file (claude_desktop_config.json):

Tip: For CLI / interactive agents that can OAuth, prefer finlet auth login to avoid hardcoding keys.
Before you copy: Replace every your_api_key_here placeholder below with the actual value — your API key from finlet register (when the client speaks the REST API), or your OAuth Bearer token from finlet auth login (when the client routes through the MCP server). The literal string your_api_key_here is not a credential.
JSON 
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"],
      "env": {
        "FINLET_API_KEY": "your_api_key_here"
      }
    }
  }
}
Note: The finlet mcp command starts the MCP server over stdio and dispatches against the hosted Finlet service at https://finlet.dev — you do not need to run your own API server. Self-hosted operators can override the target by setting FINLET_API_URL in the env block.

For any MCP-compatible client, configure a stdio transport pointing to the Finlet MCP server:

JSON 
{
  "name": "finlet",
  "transport": "stdio",
  "command": "finlet",
  "args": ["mcp"],
  "env": {
    "FINLET_API_KEY": "your_api_key_here"
  }
}
Requirements: Python 3.12+ with Finlet installed (pip install finlet). The finlet command must be available in your PATH.

If your agent does not support MCP, you can call the hosted Finlet REST API directly at https://finlet.dev. No server install required — just authenticate with the API key from Step 1.

Before you copy: Replace every your_api_key_here placeholder below with your actual API key from finlet register. The literal string your_api_key_here is not a credential.
cURL 
# Verify the API is reachable
curl https://finlet.dev/v1/health
cURL 
# Create a session
curl -X POST https://finlet.dev/v1/sessions \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "start_time": "2024-01-01", "initial_capital": 100000, "universe": ["AAPL", "GOOGL"]}'

# Get portfolio state
curl https://finlet.dev/v1/sessions/{session_id}/portfolio \
  -H "Authorization: Bearer your_api_key_here"
cURL 
# Submit a market buy order against a session
curl -X POST https://finlet.dev/v1/sessions/$SESSION_ID/trade/order \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ticker":"AAPL","side":"BUY","quantity":1,"order_type":"MARKET"}'

From the CLI, the equivalent command is:

Terminal 
finlet order --session $SID --ticker AAPL --side BUY --quantity 1

Run Your First Command

Create a session and query market data to verify everything works.

With finlet auth login complete from Step 1, create your first session:

Terminal 
finlet session create --name my-first-session --start 2024-01-01 --capital 100000 --universe AAPL,GOOGL,MSFT

Then ask your AI agent to call a Finlet MCP tool. Here is an example tool call your agent would make:

MCP Tool Call 
{
  "tool": "get_price_data",
  "arguments": {
    "ticker": "AAPL",
    "interval": "1d",
    "period": "1mo"
  }
}
Success! If your agent receives OHLCV price data in response, your connection is working. You can now start building your trading strategy.

Available MCP Tools

All 8 tools your AI agent can use via the Finlet MCP server.

Market Data

get_price_data

Get historical OHLCV price data for a ticker. Supports intervals from 1m to 1w and lookback periods from 5d to 1y.

ticker interval period

search_news

Search for news articles about a company. Optionally filter by search text.

ticker query limit

get_fundamentals

Get fundamental metrics for a company: P/E ratio, market cap, revenue, and more.

ticker

Trading

submit_order

Submit a trade order (BUY/SELL). Supports MARKET, LIMIT, and STOP order types.

ticker side quantity order_type reasoning

get_portfolio

Get current portfolio state including cash balance, open positions, and total value.

session_id

Simulation Clock

get_sim_time

Get the current simulation time, clock mode, and speed.

session_id

advance_time

Advance the simulation clock by an interval: 1d, 1h, 5m, 1w, and more.

interval session_id

freeze_time

Freeze the simulation clock. Time will not advance until you call advance_time.

session_id