Connect Your AI Agent in 3 Steps

Get your AI trading agent connected to Finlet through the MCP stdio bridge, with hosted HTTP and REST fallbacks for constrained environments.

Looking for the full reference? This page is a quickstart shell — copy a config, paste it into your agent, you're done. The binary-portable, agent-readable version of the same content lives in the finlet CLI:

Authenticate

Sign in with OAuth so the CLI and MCP stdio bridge pick up your Bearer token automatically.

Start with OAuth. Browser sign-in handles account creation when needed and writes the local credential file used by finlet mcp serve:

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). The stdio bridge reads that file when your agent host starts it.

Auth path: MCP stdio reads ~/.finlet/credentials by default and proxies to hosted /mcp. CI and other headless environments can set FINLET_API_KEY in the stdio subprocess env. Hosted MCP-over-HTTP remains available as a fallback at https://finlet.dev/mcp with an Authorization: Bearer ... header.
CI / headless / non-interactive — export FINLET_API_KEY instead

If you can't run finlet auth login (CI workers, eval rigs, anything without a browser), export your api_key. The REST API accepts it on every route, and finlet mcp serve accepts it as the stdio credential fallback.

Terminal (CI / headless) 
export FINLET_API_KEY=your_api_key_here

Configure Your Client

Pick your AI client. Each MCP tab leads with the local finlet mcp serve stdio config. Hosted HTTP and API-key fallbacks are collapsed behind details.

Stdio first. The canonical v2 config has no env, no headers, and no hosted URL. Run finlet auth login once; the subprocess reads ~/.finlet/credentials and forwards to hosted /mcp when your agent host starts it.

Local (finlet mcp serve stdio)

Add this no-env block to claude_desktop_config.json. The bridge reads the OAuth credential from ~/.finlet/credentials.

JSON 
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"]
    }
  }
}
Hosted HTTP fallback

Use this only when the client cannot spawn local stdio servers.

JSON
{
  "mcpServers": {
    "finlet": {
      "url": "https://finlet.dev/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your_oauth_jwt"
      }
    }
  }
}
Headless variant — FINLET_API_KEY in env
JSON
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"],
      "env": {
        "FINLET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local (finlet mcp serve stdio)

Register Finlet from your terminal. The no-env command relies on finlet auth login credentials already stored on disk.

Terminal 
claude mcp add finlet -- finlet mcp serve
Equivalent JSON
JSON
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"]
    }
  }
}
Hosted HTTP fallback
Terminal
claude mcp add finlet --transport http --url https://finlet.dev/mcp --header "Authorization: Bearer your_oauth_jwt"
Headless variant — FINLET_API_KEY in env
Terminal
claude mcp add finlet --command finlet --args "mcp,serve" --env "FINLET_API_KEY=your_api_key_here"

Local (finlet mcp serve stdio)

Add this no-env block to ~/.cursor/mcp.json.

JSON 
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"]
    }
  }
}
Hosted HTTP fallback
JSON
{
  "mcpServers": {
    "finlet": {
      "url": "https://finlet.dev/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your_oauth_jwt"
      }
    }
  }
}
Headless variant — FINLET_API_KEY in env
JSON
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"],
      "env": {
        "FINLET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local (finlet mcp serve stdio)

Add the server with the Codex CLI shortcut, or use the equivalent config block.

Terminal 
codex mcp add finlet -- finlet mcp serve
TOML
[mcp_servers.finlet]
command = "finlet"
args = ["mcp", "serve"]
Hosted HTTP fallback
TOML
[mcp_servers.finlet]
transport = "http"
url = "https://finlet.dev/mcp"
Authorization = "Bearer your_oauth_jwt"
Headless variant — FINLET_API_KEY in env
TOML
[mcp_servers.finlet]
command = "finlet"
args = ["mcp", "serve"]
FINLET_API_KEY = "your_api_key_here"

Local (finlet mcp serve stdio)

Add this no-env block to ~/.codeium/windsurf/mcp_config.json.

JSON 
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"]
    }
  }
}
Hosted HTTP fallback
JSON
{
  "mcpServers": {
    "finlet": {
      "url": "https://finlet.dev/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your_oauth_jwt"
      }
    }
  }
}
Headless variant — FINLET_API_KEY in env
JSON
{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"],
      "env": {
        "FINLET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local (finlet mcp serve stdio)

Add this no-env server entry to your VS Code MCP settings.

JSON 
{
  "servers": {
    "finlet": {
      "type": "stdio",
      "command": "finlet",
      "args": ["mcp", "serve"]
    }
  }
}
Hosted HTTP fallback
JSON
{
  "mcpServers": {
    "finlet": {
      "url": "https://finlet.dev/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your_oauth_jwt"
      }
    }
  }
}
Headless variant — FINLET_API_KEY in env
JSON
{
  "servers": {
    "finlet": {
      "type": "stdio",
      "command": "finlet",
      "args": ["mcp", "serve"],
      "env": {
        "FINLET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local (finlet mcp serve stdio)

Any standards-compliant MCP stdio client can use this shape.

JSON 
{
  "name": "finlet",
  "transport": "stdio",
  "command": "finlet",
  "args": ["mcp", "serve"]
}
Hosted HTTP fallback
JSON
{
  "name": "finlet",
  "transport": "http",
  "url": "https://finlet.dev/mcp",
  "headers": {
    "Authorization": "Bearer your_oauth_jwt"
  }
}
Headless variant — FINLET_API_KEY in env
JSON
{
  "name": "finlet",
  "transport": "stdio",
  "command": "finlet",
  "args": ["mcp", "serve"],
  "env": {
    "FINLET_API_KEY": "your_api_key_here"
  }
}
Requirements: Python 3.12+ with Finlet installed using pip install finlet. The finlet command must be available in your PATH.

REST (https://finlet.dev/v1/...)

If your agent does not speak MCP, call the hosted Finlet REST API directly. REST accepts either X-API-Key: fnlt_<key> or Authorization: Bearer fnlt_<key>. OAuth Bearer is also accepted when you can mint one via finlet auth login.

cURL 
curl https://finlet.dev/v1/health
cURL
curl -X POST https://finlet.dev/v1/sessions \
  -H "X-API-Key: $FINLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"test","start_time":"2024-01-01","initial_capital":100000,"universe":["AAPL","GOOGL"]}'

From an MCP-connected agent, ask in natural language and the agent invokes create_session, submit_order, and get_portfolio for you.

Run Your First Command

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

With finlet auth login complete from Step 1 and your agent host wired to finlet mcp serve from Step 2, ask your agent to create your first session in natural language — the agent calls the create_session MCP tool for you:

Ask your agent 
Create a session named 'my-first-sim' starting 2024-01-02 with $100,000
capital and tickers AAPL, MSFT, GOOGL. Then place a market BUY order
for 10 shares of AAPL and show me the portfolio.

Under the hood the agent invokes create_session, submit_order, and get_portfolio via MCP. Here is what one of those tool calls looks like on the wire:

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

Core tools your AI agent can use via the Finlet MCP server. Run finlet manual plugin-matrix for the per-plugin reference with rate limits and error envelopes.

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

Troubleshooting

Top 5 issues seen in the field. Each row deep-links to the canonical anchor in the finlet CLI's error catalog — run the command in your terminal for the full envelope, source code path, and recovery action.

  • Rate limit hit

    An upstream plugin (Finnhub, FRED) or the per-tenant HTTP gate returned a 429. The envelope embeds the exact reset window — back off for that duration, then retry. Do not poll faster.

    View in CLI: finlet manual errors#rate-limit

  • Expired or missing OAuth token

    MCP-over-HTTP at https://finlet.dev/mcp requires Authorization: Bearer <jwt>. If your token is near or past its exp claim, the stdio bridge refreshes transparently before the next hosted MCP call. If it's missing entirely, run finlet auth login to mint a fresh one — or rebind the client to the stdio bridge.

    View in CLI: finlet manual errors#expired-token · finlet manual errors#missing-bearer

  • Missing API key for a plugin

    Plugins that require credentials (Finnhub, FRED, EDGAR) fail with a specific envelope naming the missing key. Set the corresponding env var (FINNHUB_API_KEY, FRED_API_KEY) in your shell or the stdio bridge's env block. Plugins without keys remain healthy on the free tier path.

    View in CLI: finlet manual errors#missing-api-key

  • 401 on /mcp — invalid or missing Bearer

    The MCP HTTP surface at /mcp accepts both Authorization: Bearer <oauth_jwt> and Authorization: Bearer fnlt_<key> (dual-accept, same as REST). A 401 means the Bearer didn't validate — the JWT is expired/malformed and the api_key didn't match. Mint a fresh OAuth token with finlet auth login, or double-check the fnlt_<key> matches the current one in your dashboard.

    View in CLI: finlet manual errors#missing-bearer

  • finlet serve port conflict

    If finlet serve or finlet mcp serve fails to bind, another process owns the port. Find it with lsof -i :<port> and either kill it or pass --port=<other> / FINLET_PORT=<other> to relocate Finlet.

    View in CLI: finlet manual errors#port-conflict

Need a different error? The CLI's error catalog ships 13 stable anchors: #rate-limit, #expired-token, #missing-bearer, #missing-scope, #missing-api-key, #plugin-timeout, #plugin-malformed, #plugin-rate-limit, #transport-mismatch, #port-conflict, #date-ceiling-violation, #invalid-session, #order-rejected. Run finlet manual errors for the full catalog.