robinhood-agentic-mcp/docs/superpowers/specs/2026-09-01-robinhood-agentic-mcp-design.md

# robinhood-agentic-mcp

**Date:** 2026-09-01  
**Status:** approved design, pending implementation plan  
**Product:** `robinhood-agentic-mcp` — a Go library that presents the full Robinhood Agentic MCP with the same transport and auth tradey already uses.

Not investment advice. The caller is responsible for every fill in the Robinhood Agentic account.

## Goal

A standalone Go module at `/fast/projects/golang/robinhood-agentic-mcp` that:

1. Connects to `https://agent.robinhood.com/mcp/trading` the way tradey does today (OAuth, token file, streamable HTTP session, JSON-RPC fallback).
2. Exposes a typed Go method for every tool on that MCP (equity, options, crypto, watchlists, market data, scanner, accounts).
3. Uses Alpaca-shaped money and order enums on the public API, translating to Robinhood’s string wire format internally.
4. Can be imported later by tradey; this effort does **not** rewire tradey.

## Non-goals (v1)

- A CLI binary (`login` stays a library function; tradey keeps `tradey login`).
- Rewiring tradey to import this module.
- Tradey’s `Reader` / `Executor` / `Snapshot` / `Fake` desk types (paper/live policy stays in the app).
- Codegen from `tools/list`.
- Proxying or re-hosting the MCP as a server.
- Banking / credit-card MCP (`agent.robinhood.com` non-trading endpoints).

## Operator contract

```go
type Config struct {
    URL       string // empty → DefaultURL
    TokenFile string
    Name      string // MCP Implementation.Name and OAuth ClientName; empty → "robinhood-agentic-mcp"
    Version   string // MCP Implementation.Version; empty → "0.1.0"
}

func Login(ctx context.Context, cfg Config) (accountID string, err error)
func Connect(ctx context.Context, cfg Config) (*API, error)
```

`Config` is defined in `auth` (Login owns identity and the token file). `rh` re-exports it as `type Config = auth.Config` so callers can import once. This avoids an import cycle (`rh` → `auth` → not `rh`).

| Call | Behavior |
|---|---|
| `auth.Login` / `rh.Login` | If `ROBINHOOD_ACCESS_TOKEN` is set, write it (and optional `ROBINHOOD_REFRESH_TOKEN`) to `cfg.TokenFile` mode `0600`. Otherwise run the browser OAuth dance using `cfg.Name` / `cfg.Version` and persist the full token set. |
| `rh.Connect` | Read `cfg.TokenFile`, open a session identified as `cfg.Name`/`cfg.Version`, return an `rh.API` with all subclients wired. Fail closed if tokens are missing or the session cannot be used. |
| `client.Call(ctx, name, args)` | Escape hatch: invoke any tool by MCP name and return JSON. |

Identity must be set on `Config` **before** `Login` or `Connect`. After a session exists it is not changeable. Apps that need a distinct Robinhood OAuth client (tradey, another bot) pass their own `Name`. Empty `Name`/`Version` keep the library defaults.

Daemon/headless callers must not call `Login` (no browser). They call `Connect` with an existing token file.

## Architecture

Module path: `s1d3sw1ped/robinhood-agentic-mcp`  
Go version: `1.25`  
Default MCP URL: `https://agent.robinhood.com/mcp/trading`  
MCP SDK: `github.com/modelcontextprotocol/go-sdk` (same major as tradey, currently v1.7.0)

One shared session. Asset-class packages wrap it. The root package is a facade so a caller can import once.

```
s1d3sw1ped/robinhood-agentic-mcp          // rh: DefaultURL, Config, Connect, API, shared enums
  client/                                 // session, Call, ToolError, transport
  auth/                                   // Login, TokenSet, Read/Write tokens
  internal/wire                           // unwrap data envelopes, decimal JSON
  internal/rhntest                        // httptest Robinhood MCP mock
  accounts/
  equity/
  options/
  crypto/
  watchlists/
  market/
  scanner/
```

```go
package rh

const DefaultURL = "https://agent.robinhood.com/mcp/trading"

type API struct {
    Client     *client.Client
    Accounts   *accounts.Client
    Equity     *equity.Client
    Options    *options.Client
    Crypto     *crypto.Client
    Watchlists *watchlists.Client
    Market     *market.Client
    Scanner    *scanner.Client
}

func Connect(ctx context.Context, cfg Config) (*API, error)
func Login(ctx context.Context, cfg Config) (accountID string, err error) // re-exports auth.Login
```

Empty `cfg.URL` means `DefaultURL`. Subpackages also export `New(c client.Caller) *Client` so callers can wire a single package without the facade.

Each subclient depends only on `client.Caller`. Unit tests inject a stub; transport tests hit `rhntest`. A future tradey adapter can inject the same caller.

## Auth and transport

Copied from tradey’s working path (`internal/broker/oauth.go`, `login.go`, `mcp.go`). Identity is caller-owned via `Config.Name` / `Config.Version` so each app is a distinct Robinhood OAuth client (tradey, this library’s default, Grok-chat MCP, and so on).

- MCP `Implementation.Name` / `Implementation.Version`: `cfg.Name`, `cfg.Version` (defaults `robinhood-agentic-mcp` / `0.1.0`).
- OAuth dynamic client registration `ClientName`: the same `cfg.Name`.
- OAuth callback page text uses `cfg.Name` (not a hardcoded “Tradey is signed in”).
- `StreamableClientTransport` with `DisableStandaloneSSE: true`.
- Prefer the SDK session `CallTool`. If session connect fails, fall back to HTTP POST JSON-RPC `tools/call` with `Authorization: Bearer` and `Accept: application/json, text/event-stream`.
- Token file JSON matches tradey’s `TokenSet` (access, refresh, type, expiry, client_id/secret, auth/token/redirect URLs, account_id). Mode `0600`.
- `Login` timeout: 5 minutes for the OAuth dance.
- Session connect does not prompt; expired OAuth returns an error telling the caller to run `Login` again.
- Connect does **not** write refreshed tokens back to disk (v1). The token file is whatever `Login` last wrote.

`client.Caller`:

```go
type Caller interface {
    Call(ctx context.Context, name string, args map[string]any) (json.RawMessage, error)
}
```

## Typed API conventions

Every MCP tool is `func (c *Client) Method(ctx context.Context, req Request) (Result, error)`.

- Method names drop the `get_` prefix: `Quotes`, `Positions`, `PlaceOrder`, `CancelOrder`.
- The MCP tool name is a private constant next to the method (`toolQuotes = "get_equity_quotes"`).
- Request structs use `omitempty` on the wire map. Optional MCP fields are pointers or zero-means-omit.
- `client.Call` stays public.

### Money (Alpaca-shaped)

Public money, size, and price fields use `github.com/alpacahq/alpacadecimal` imported as `decimal`, so the type name is `decimal.Decimal` like `alpaca-trade-api-go`.

- Required amounts: `decimal.Decimal`.
- Optional amounts: `*decimal.Decimal` (Alpaca `PlaceOrderRequest.Qty` / `LimitPrice`).
- Never `float64` for money, size, prices, buying power, volume, or bar OHLC.

On the way out, encode with `Decimal.String()` onto Robinhood’s string fields (`quantity`, `limit_price`, `stop_price`, `dollar_amount`, option `price`). On the way in, accept JSON string **or** number (tradey’s envelope) and parse into `decimal.Decimal`.

Parse rules for money/size/price:

| JSON | Optional `*decimal.Decimal` | Required `decimal.Decimal` |
|---|---|---|
| field omitted or JSON `null` | `nil`, not an error | zero value, not an error |
| `0` / `"0"` / `"0.0"` | pointer to zero | zero |
| `""` | `nil`, not an error | zero, not an error |
| valid number or numeric string | parsed value | parsed value |
| present but unparseable (`"n/a"`, object, bool, array) | **error** (`ToolError` parse), never silent zero/nil | **error**, never silent zero |

Failed parsing is never coerced into zero or nil. Absent/intentional empty is never treated as a parse failure.

### Enums (Alpaca-shaped names, Robinhood wire values)

Exported from the root `rh` package:

```go
type Side string
const (
    Buy  Side = "buy"
    Sell Side = "sell"
)

type OrderType string
const (
    Market    OrderType = "market"
    Limit     OrderType = "limit"
    Stop      OrderType = "stop_market" // equity + options; crypto uses StopLoss
    StopLimit OrderType = "stop_limit"
    StopLoss  OrderType = "stop_loss"   // crypto only
)

type TimeInForce string
const (
    GFD TimeInForce = "gfd"
    GTC TimeInForce = "gtc"
    GFW TimeInForce = "gfw" // crypto
    GFM TimeInForce = "gfm" // crypto
)

type MarketHours string
const (
    RegularHours              MarketHours = "regular_hours"
    ExtendedHours             MarketHours = "extended_hours"
    AllDayHours               MarketHours = "all_day_hours"
    RegularCurbHours          MarketHours = "regular_curb_hours"
    RegularCurbOvernightHours MarketHours = "regular_curb_overnight_hours"
)
```

Callers write `rh.Buy`, `rh.Limit`, `rh.GFD`. The library does not map Alpaca’s `"day"` / `"stop"` onto Robinhood; the const **values** are Robinhood’s.

## Errors

```go
type ToolError struct {
    Name    string // MCP tool name
    Message string
    Err     error  // transport/SDK/parse cause; may be nil
}

func (e *ToolError) Error() string  // "mcp <name>: <message>"
func (e *ToolError) Unwrap() error
```

`Call` and every typed method return `*ToolError` (or wrap one) on tool/transport failure so callers can `errors.As`. Parse failures use the same type with `Name` set and `Message` like `parse quotes`. Login/Connect fail closed: no empty client, no nil-session success.

HTTP ≥300, JSON-RPC `error`, and SDK `CallTool` errors all become `ToolError`.

## Tool map

Source of truth for coverage is a frozen `testdata/tools.json` captured from live `tools/list` during implementation (checked in, not refreshed by CI). Every name in that fixture must have a typed method. The tables below are the known inventory (Robinhood’s “Trading with your agent” page plus extra tools already on the connected MCP). Names that appear in the fixture but not in a table still get a method in the matching package in the same PR (`get_advanced_orders` → `equity`).

### `accounts`

| MCP tool | Method |
|---|---|
| `get_accounts` | `Accounts` |
| `get_portfolio` | `Portfolio` |
| `get_realized_pnl` | `RealizedPnL` |
| `get_pnl_trade_history` | `PnLTradeHistory` |
| `get_limited_margin_upgrade_info` | `LimitedMarginUpgradeInfo` |
| `get_option_level_upgrade_info` | `OptionLevelUpgradeInfo` |
| `get_crypto_account_onboarding_info` | `CryptoOnboardingInfo` |
| `search` | `Search` |

This library does **not** enforce tradey’s `supported()` account policy (IRA/UTMA/full margin bans). It returns whatever `get_accounts` returns, including `agentic_allowed`. Apps decide.

### `equity`

| MCP tool | Method |
|---|---|
| `get_equity_positions` | `Positions` |
| `get_equity_tax_lots` | `TaxLots` |
| `get_equity_quotes` | `Quotes` |
| `get_equity_orders` | `Orders` |
| `get_equity_tradability` | `Tradability` |
| `get_equity_historicals` | `Historicals` |
| `get_equity_fundamentals` | `Fundamentals` |
| `get_equity_price_book` | `PriceBook` |
| `get_equity_technical_indicators` | `TechnicalIndicators` |
| `get_equity_news` | `News` |
| `review_equity_order` | `ReviewOrder` |
| `place_equity_order` | `PlaceOrder` |
| `cancel_equity_order` | `CancelOrder` |

`Historicals` accepts caller interval/bounds/adjustment (no hidden tradey `minute`/`regular` defaults). Batching more than 10 symbols is the caller’s job; the method sends one MCP call.

### `options`

| MCP tool | Method |
|---|---|
| `get_option_chains` | `Chains` |
| `get_option_instruments` | `Instruments` |
| `get_option_quotes` | `Quotes` |
| `get_option_positions` | `Positions` |
| `get_option_orders` | `Orders` |
| `get_option_historicals` | `Historicals` |
| `review_option_order` | `ReviewOrder` |
| `place_option_order` | `PlaceOrder` |
| `cancel_option_order` | `CancelOrder` |
| `replace_option_order` | `ReplaceOrder` |
| `exercise_option` | `Exercise` |
| `cancel_option_exercise` | `CancelExercise` |

### `crypto`

| MCP tool | Method |
|---|---|
| `get_currency_pairs` | `Pairs` |
| `get_crypto_quotes` | `Quotes` |
| `get_crypto_positions` | `Positions` |
| `get_crypto_orders` | `Orders` |
| `preview_crypto_order` | `PreviewOrder` |
| `place_crypto_order` | `PlaceOrder` |
| `cancel_crypto_order` | `CancelOrder` |

Crypto account numbers use `rhs_account_number` on the wire, named `RHSAccountNumber` in request structs.

### `watchlists`

| MCP tool | Method |
|---|---|
| `get_watchlists` | `Lists` |
| `get_watchlist_items` | `Items` |
| `get_option_watchlist` | `OptionList` |
| `get_popular_watchlists` | `Popular` |
| `create_watchlist` | `Create` |
| `update_watchlist` | `Update` |
| `follow_watchlist` | `Follow` |
| `unfollow_watchlist` | `Unfollow` |
| `add_to_watchlist` | `Add` |
| `remove_from_watchlist` | `Remove` |
| `add_option_to_watchlist` | `AddOption` |
| `remove_option_from_watchlist` | `RemoveOption` |

No title-lookup helper in v1. Tradey’s `Watchlist(title)` (match title, then `get_watchlist_items`, keep equity/ETF) stays in tradey until rewire.

### `market`

| MCP tool | Method |
|---|---|
| `get_indexes` | `Indexes` |
| `get_index_quotes` | `IndexQuotes` |
| `get_index_historicals` | `IndexHistoricals` |
| `get_financials` | `Financials` |
| `get_earnings_results` | `EarningsResults` |
| `get_earnings_calendar` | `EarningsCalendar` |
| `get_sec_filing_index` | `SECFilingIndex` |
| `get_sec_filing` | `SECFiling` |
| `get_sec_filing_facts` | `SECFilingFacts` |
| `get_sec_filing_facts_catalog` | `SECFilingFactsCatalog` |

### `scanner`

| MCP tool | Method |
|---|---|
| `get_scanner_filter_specs` | `FilterSpecs` |
| `get_scanner_datapoints` | `Datapoints` |
| `get_scans` | `Scans` |
| `create_scan` | `Create` |
| `preview_scan` | `Preview` |
| `run_scan` | `Run` |
| `update_scan_filters` | `UpdateFilters` |
| `update_scan_config` | `UpdateConfig` |

If the captured fixture omits a table row (tool removed upstream), drop that method rather than stub a dead tool. Do not ship a library that silently drops tools that are still listed.

## Data flow

```
Login(Config)  → browser OAuth or env token → tokens.json (0600), OAuth client = cfg.Name
Connect(Config) → ReadTokens → session (or RPC fallback) as cfg.Name/cfg.Version → rh.API
API.Equity.PlaceOrder(ctx, req)
  → map req to MCP args (decimal.String, rh.Limit → "limit")
  → client.Call("place_equity_order", args)
  → toolJSON / unwrap data
  → parse into Result (decimal from string|number)
```

Pagination: request structs take `Cursor string`; results expose `NextCursor` / `Next` when the MCP returns one. No auto-paging in v1.

## Testing

CI must not call the live broker or open a browser. Tests otherwise go as far as they can: they hit an in-process Robinhood MCP mock over HTTP, not only an injected `Caller`.

`internal/rhntest` is an `httptest.Server` that speaks Robinhood’s MCP surface the way tradey talks to it:

- Required protocol: JSON-RPC `tools/call` (tradey’s RPC fallback). Optional extra: streamable-HTTP `CallTool` if the SDK client can talk to the same httptest without extra machinery.
- Requires `Authorization: Bearer` when the test sets a token.
- Dispatches on tool name and returns checked-in envelope fixtures (`testdata/*.json`) shaped like live Robinhood (`data` wrappers, string-or-number amounts, quote/close objects).
- Can return HTTP 4xx, JSON-RPC errors, and malformed bodies so `ToolError` and parse-error paths are exercised.

Required tests:

- **Transport:** `Connect` against `rhntest` (session if the mock can serve it, otherwise RPC fallback), bearer header, HTTP error → `ToolError`, identity `Name`/`Version` sent on the MCP initialize/OAuth client metadata.
- **Every typed method:** (1) stub `Caller` asserting MCP tool name + JSON args including `decimal.String()`; (2) round-trip through `rhntest` with a realistic success fixture.
- **Wire/decimal:** omitted/null/`""`/`0` vs unparseable (`"n/a"`, object) — the latter errors, the former does not.
- Parser fixtures from tradey’s known envelopes: `accounts` with `data` wrapper, quotes as `{quotes:[{quote:{…}, close:{…}}]}`, historicals `{historicals:[{symbol, data_points}]}`, watchlists `title` vs `name`.
- `WriteTokens` mode `0600`.
- `Login` from `ROBINHOOD_ACCESS_TOKEN` (no OAuth, no browser).
- `ToolError` is `errors.As`-able.
- Coverage: frozen `testdata/tools.json` from live `tools/list` must have a method for every name.

No live-MCP or browser-OAuth in default `go test`. An optional `//go:build live` smoke is out of v1.

## Package map

| Package | Does | Depends on |
|---|---|---|
| `rh` | `Config`, `Connect`, `Login`, `API`, enums | all subpackages |
| `client` | session, `Call`, `ToolError`, RPC fallback | MCP SDK, oauth2 |
| `auth` | `Login`, token file | `client` (session during OAuth), MCP auth/oauthex |
| `internal/wire` | unwrap `data`, decimal JSON | alpacadecimal |
| `internal/rhntest` | httptest Robinhood MCP mock | `client` protocol |
| `accounts` … `scanner` | typed methods | `client.Caller`, `rh` enums, `internal/wire` |

## Success criteria

- `go test ./...` passes with no live network (httptest mock only).
- Typed methods work with an injected `Caller` **and** round-trip through `rhntest`.
- `Connect`/`Login` accept `Config.Name` / `Config.Version`; empty uses library defaults.
- `Login` with `ROBINHOOD_ACCESS_TOKEN` writes `0600` tokens.
- `equity.PlaceOrder` sends `quantity`/`limit_price` as decimal strings, `time_in_force` `gfd`, `type` `limit` — matching tradey’s `placeArgs` for the same inputs.
- Every name in the frozen `tools/list` fixture has a method.
- tradey still builds; this repo does not import tradey and tradey is not changed.

## Out of scope until tradey rewire

- `Watchlist(title string) ([]string, error)` helper.
- Composite `Snapshot`.
- Paper `Executor` constructor split.
- `replace` directive / `go.mod` change in tradey.