MCP Quickstart
Connect Starkscan to Codex, Claude Code, and similar MCP clients without losing the app and API context.
Loading documentation content…
Connect Starkscan to Codex, Claude Code, and similar MCP clients without losing the app and API context.
Use this guide when a tool-calling client needs Starkscan over MCP. Do not start here if a normal service can call HTTP directly or if a human operator is better served by the CLI.
Hosted MCP HTTP is currently beta; the @starkscan/mcp launcher package is alpha.
Check the Launch matrix before treating a launcher or hosted transport path as production-ready.
For npm package provenance, Socket links, and exact-version pinning rules, use
Package trust.
| Surface | Public label | What works today |
|---|---|---|
| REST core API | certified | Direct /v1/{chain}/* REST calls for the certified route set, including timestamp-to-block plus exact token balance for accounting. Use this when a normal service can call HTTP. |
| TypeScript SDK | alpha | Typed application code over the same REST contract. |
| Agent CLI | alpha | Shell workflows and local exports with the same STARKSCAN_* environment variables. |
| Hosted MCP | beta hosted / alpha launcher | /api/mcp is the hosted HTTP beta; @starkscan/mcp@alpha launches the client bridge. |
Before you connect an agent, look at the same explorer surfaces on the current host:
That keeps the agent workflow grounded in the same product behavior that Starkscan users actually see.
Today the cleanest setup is:
STARKSCAN_* variables used by REST and CLInpx -y @starkscan/mcp@alphaUse STARKSCAN_* for new beta clients. Legacy internal env names are accepted only as hidden compatibility aliases during the cutover.
tools/list should expose 18 tools total: bootstrap guidance plus 17 route tools.
export STARKSCAN_BASE_URL="https://<your-starkscan-host>/api"
export STARKSCAN_API_KEY="<set in your local shell or agent secret store>"
export STARKSCAN_CHAIN="SN_MAIN"Print client config locally before wiring an agent. The output contains
${STARKSCAN_API_KEY} placeholders, not secret values:
npx -y @starkscan/mcp@alpha print-config --transport remotecodex mcp add starkscan \
--env STARKSCAN_BASE_URL=$STARKSCAN_BASE_URL \
--env STARKSCAN_API_KEY=$STARKSCAN_API_KEY \
--env STARKSCAN_CHAIN=$STARKSCAN_CHAIN \
-- npx -y @starkscan/mcp@alphaUseful starter tools for Starkscan agent workflows:
statusblock_detailblock_transactionstoken_total_supplytoken_balance_oftoken_transferssearch is identifier-first, not ticker or symbol search, and some responses normalize into canonical padded felt forms.contract_entrypoints is broader than contract_read; for read, prefer selectors with stateMutability=view and pass required calldata.address_token_holdings is the wallet-screening surface. Treat it as complete only when exact=true, truncated=false, and completeness.reasonCode="complete".latest calls to holdings and token_balance_of can drift numerically if the chain moved between requests. Missing a core-token row on a completed holdings response is the stronger bug signal.claude mcp add --scope project --transport stdio \
--env STARKSCAN_BASE_URL=$STARKSCAN_BASE_URL \
--env 'STARKSCAN_API_KEY=${STARKSCAN_API_KEY}' \
--env STARKSCAN_CHAIN=$STARKSCAN_CHAIN \
starkscan -- npx -y @starkscan/mcp@alphaCheck that Claude Code sees it:
claude mcp listStarkscan also exposes a native HTTP MCP endpoint at:
{baseUrl}/mcp (for hosted external clients, this resolves to /api/mcp)This is documented here instead of the REST reference because it is a JSON-RPC transport, not the normal explorer HTTP surface.
Current behavior:
POST {baseUrl}/mcp accepts one JSON-RPC message per requestapplication/json202 AcceptedGET {baseUrl}/mcp returns 405 Method Not AllowedSTARKSCAN_BASE_URL="https://<your-starkscan-host>/api" \
STARKSCAN_API_KEY="$STARKSCAN_API_KEY" \
./rust-exp/scripts/release-mcp-remote-smoke.shThis exercises a real JSON-RPC session over stdio:
initializenotifications/initializedtools/listtools/call for the bootstrap guidance tooltools/call for statustools/call for block_detail