Connect an AI Agent to Alpaca with the Official MCP Server (Paper-First Setup)

Alpaca is the one major broker where your agent can rehearse with fake money before it ever touches real money. The official alpaca-mcp-server defaults to paper trading — a free simulated account with a resettable $100k balance and real-time market data. That makes Alpaca the best on-ramp in this entire guide: every mistake your agent is going to make, it can make for free first.

It also has the largest tool surface of any broker setup we cover — stocks, ETFs, options including multi-leg spreads, and crypto, across roughly 60 tools. More capability means more to fence in. This guide sets it up in the order that keeps you safe: paper first, scoped always, live last.

Before you start

Create a free account at alpaca.markets and open a paper account from the dashboard — no funding needed. Generate the paper account’s API key pair. You’ll also need uv (the Python package runner; the server is Python 3.10+) and any MCP-capable agent — the examples below use Claude Desktop, and the same server works with Claude Code, Cursor, and Gemini CLI.

Unlike Robinhood’s hosted MCP endpoint, Alpaca’s server runs locally on your machine — there is no official hosted version. That cuts both ways: you can read its source (it’s open source, github.com/alpacahq/alpaca-mcp-server), but the API keys sit in your agent’s config file. Treat that file like a password.

Step 1 — Connect, in paper mode

Add the server to your agent’s MCP config. For Claude Desktop, that’s claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_paper_api_key",
        "ALPACA_SECRET_KEY": "your_paper_secret_key",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

Restart the agent fully, then verify with a read-only question: "What’s my Alpaca account balance?" You should see the paper account’s simulated cash. Two notes: ALPACA_PAPER_TRADE is true by default, but set it explicitly — your safety posture should never depend on remembering a default. And never paste API keys into the chat itself; they belong in the config’s env block only.

Step 2 — Scope the tool surface

Alpaca’s server exposes options and crypto tools alongside stock orders. If your plan is bounded equities trading — and for a first agent it should be — say so explicitly, twice. First in your guardrail config (the Safety Kit generates the equities-only rule). Second, where supported, at the tool layer: the server reads an ALPACA_TOOLSETS environment variable that loads only the tool categories you name, and agents with tool allowlists (like Gemini CLI’s includeTools) can narrow it further. A multi-leg options spread your agent can’t see is a multi-leg options spread a poisoned headline can’t talk it into.

Step 3 — Rehearse like it’s real

The paper account is only useful if you treat it as a dress rehearsal, not a sandbox to ignore. Run your actual plan for one to two weeks:

Give the agent your real guardrail config, scaled to the funding you intend to use live — not the fake $100k. A rehearsal against a $100k balance teaches you nothing about a $1k account’s caps.
Run the monitoring routine and the trade audit as if money were moving.
Try to break it: ask the agent to exceed your caps, feed it an ambiguous instruction, watch what it does. Paper mode is the one place where what can go wrong is free to observe.

Step 4 — Graduate deliberately

Going live is a key swap, not a flag flip: generate a separate live API key pair, replace the keys in the config, set ALPACA_PAPER_TRADE to false, and fund the live account with only your bounded amount. Before the first live order, re-run the basics — balance check, one small in-cap test order, kill-switch drill (here, that’s removing the server from the config and restarting the agent, plus revoking the API key in the Alpaca dashboard for the hard stop).

If the agent did anything surprising in paper mode that you haven’t fully explained, you’re not done rehearsing. The graduation criterion is boring weeks, not exciting ones.

Good to know

Paper trading mirrors live trading closely but not perfectly — fills are simulated, so slippage and partial fills behave more politely than reality. Don’t let a smooth paper run inflate your confidence in the strategy; its job is to validate the plumbing and the guardrails. And the standing rule applies here too: prompt-level guardrails are advisory, and an agent can be steered into ignoring them — caps, scoped tools, and your own monitoring are what hold.

Alpaca gives you a free environment to practice running an agent. Recognizing when that agent is being manipulated is the skill that carries over to real money — and it’s measurable. Test yours at secprove.com.

Connect an AI Agent to Alpaca — the Paper-First Setup