Skip to content
StockSync
Docs · MCP server

Interfaces

StockSync MCP server

stocksync-mcp gives AI agents read-only access to Robinhood Chain Stock Token data over the Model Context Protocol. It serves the same StockSync Core results as the CLI and SDK.

It cannot sign, transfer, approve, or trade, and it holds no keys. Every tool is annotated readOnlyHint: true, destructiveHint: false. Nothing it returns is investment advice.

Connect a client

The server speaks MCP over stdio. Use an absolute path to the built file.

Claude Code

bash
claude mcp add stocksync -- node /absolute/path/to/stocksync/packages/mcp/dist/stocksync-mcp.mjs

# With a dedicated RPC endpoint (recommended; the public one is rate-limited)
claude mcp add stocksync --env STOCKSYNC_RPC_URL_MAINNET=https://your-rpc.example \
  -- node /absolute/path/to/stocksync/packages/mcp/dist/stocksync-mcp.mjs

Clients configured with an mcpServers file (Claude Desktop, Cursor, and others):

json
{
  "mcpServers": {
    "stocksync": {
      "command": "node",
      "args": ["/absolute/path/to/stocksync/packages/mcp/dist/stocksync-mcp.mjs"],
      "env": { "STOCKSYNC_CHAIN": "mainnet" }
    }
  }
}

During development, node packages/mcp/src/bin.ts runs the TypeScript source directly on Node.js 24.

Tools

ToolUse it to
search_stock_tokensFind tokens by ticker, company name, ISIN, or address. Discovery only, not verification
list_stock_tokensPage through every registry token in ticker order (limit, offset, nextOffset)
get_stock_tokenGet a registry entry by symbol or address (exactly one); found: false when unlisted
get_stock_priceRaw underlying quote and token-equivalent value; includeOracle adds the Chainlink feed price
verify_stock_tokenCheck whether an address is a canonical deployment, optionally for an expectedSymbol
get_multiplierRegistry multiplier vs the contract's ERC-8056 uiMultiplier, including any scheduled change
get_corporate_actionsProcessed corporate actions for one ticker or all, newest process date first
get_trading_statusAsset status, active trading halt, and whole/fractional tradability per session
get_chain_infoChain ID, explorer, Multicall3, and whether a public RPC is in use (configured RPC URLs stay private)
inspect_stock_tokenEverything above for one token in a single call; unavailable sections are null with a warning

Tools that take chain accept "mainnet" (4663) or "testnet" (46630) and default to STOCKSYNC_CHAIN.

Results

Every tool declares an output schema. A result carries structuredContent and the same JSON as a text block for clients that do not read structured content.

json
{
  "found": true,
  "chainId": 4663,
  "token": { "symbol": "NVDA", "…": "…" },
  "canonicalDeployment": {
    "chainId": 4663,
    "address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC"
  },
  "freshness": {
    "source": "robinhood-stock-token-api",
    "fetchedAt": "2026-09-15T08:00:00.000Z",
    "sourceTimestamp": null,
    "state": "fresh",
    "ageSeconds": 0,
    "maxAgeSeconds": 600,
    "fromCache": false,
    "staleFallback": false
  },
  "warnings": []
}
  • freshness.state is fresh, stale, or unknown. staleFallback: true means the upstream failed and older cached data was served.
  • warnings lists non-fatal issues such as an unavailable section, a multiplier mismatch, or a price feed past its heartbeat.
  • A lookup that finds nothing is a normal result (found: false), not an error.

Canonical status

Only verify_stock_token (and the verification section of inspect_stock_token) establishes canonical status, and only from the Robinhood Stock Token registry. A not-canonical result means StockSync cannot confirm the contract; the explanation field says so, and it is not evidence that the contract is malicious. Search matches never imply canonical status.

Price semantics

FieldBasis
underlyingQuoteRaw underlying-equity bid and ask, not multiplier-adjusted
tokenEquivalentUnderlying quote × current registry multiplier, exact
oracle.priceChainlink feed price of one token, already multiplier-adjusted
oracle.underlyingEquivalentFeed price ÷ onchain multiplier, rounded half-even

Errors

Failures return isError: true with a text message and structured content the agent can act on:

json
{ "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "…", "retryable": true } }
CodeMeaning
NOT_FOUNDThe ticker is not listed (for tools that need a listed token)
INVALID_INPUT, UNSUPPORTED_CHAIN, UNSUPPORTED_CONTRACTThe request cannot succeed as written, for example an oracle read on testnet
UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUTTransient upstream failure
UPSTREAM_RATE_LIMITEDThe upstream is rate limiting; wait before retrying
UPSTREAM_HTTP_ERROR, UPSTREAM_SCHEMA_MISMATCHThe upstream rejected the request or returned data StockSync cannot validate
RPC_ERRORA Robinhood Chain RPC read failed

Use retryable rather than the code to decide whether to try again.

Malformed arguments (for example an address that is not 40 hex characters, both symbol and address, or an unknown argument name such as include_oracle) return an Input validation error result before any upstream is called. Error messages never include upstream URLs or configured RPC endpoints.

Environment

The server reads the same variables as StockSync Core:

VariablePurpose
STOCKSYNC_CHAINDefault chain for tools that take chain
STOCKSYNC_RPC_URL_MAINNETDedicated mainnet RPC (the public endpoint is rate-limited)
STOCKSYNC_RPC_URL_TESTNETDedicated testnet RPC
STOCKSYNC_HTTP_TIMEOUT_MSPer-request timeout, 500 to 60000 ms
STOCKSYNC_API_BASE_URLStock Token API base URL
STOCKSYNC_CHAINLINK_FEEDS_URLChainlink feed directory for mainnet

An invalid value stops the server at startup with exit code 5 and the variable name on stderr. stdout carries only MCP protocol messages.