MCP quickstart

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; @starkscan/mcp availability is registry-authoritative. The 0.4.0 verification target is usable only when its live registry resolution and post-publish proof agree. Check the Launch matrix before treating a launcher or hosted transport path as stable. For npm package provenance, Socket links, and exact-version pinning rules, use Package trust.

Use this surface for

• Codex, Claude Code, and other tool-calling clients
• workflows where an agent needs Starkscan tools instead of raw REST requests
• reusing the same Starkscan auth policy while keeping rollout access bounded

Current labels

Try in app first

Before you connect an agent, look at the same explorer surfaces on the current host:

• Dashboard
• Transactions
• Contracts
• Watchlist

That keeps the agent workflow grounded in the same product behavior that Starkscan users actually see.

Current external setup

Today the cleanest setup is:

1. export the same STARKSCAN_* variables used by REST and CLI
2. let the AI client launch npx -y @starkscan/mcp
3. install the CLI from the Agent CLI guide only when you want lower-level shell commands

Use STARKSCAN_* for new clients. Legacy internal env names are accepted only as hidden compatibility aliases during the cutover. Use untagged @starkscan/mcp for normal setup. Keep unattended MCP host configs pinned to a version resolved from npm latest when reproducibility matters. Treat the 0.4.0 verification target as available only when the registry and post-publish proof agree. tools/list should expose 18 tools total: bootstrap guidance, 16 read route tools, and the contract_write_payload unsigned write-payload builder.

Environment

export STARKSCAN_API_KEY="<set in your local shell or agent secret store>"
export STARKSCAN_CHAIN="SN_MAIN"
# Optional: only set this for preview or self-hosted hosts.
# export STARKSCAN_BASE_URL="https://preview.example.com/api"

Print client config locally before wiring an agent. The output contains ${STARKSCAN_API_KEY} placeholders, not secret values:

npx -y @starkscan/mcp print-config --transport remote

Before saving an MCP configuration, resolve the current released launcher once. The saved commands below expand this value immediately, so they retain an exact version rather than npm's moving latest tag:

STARKSCAN_MCP_VERSION="$(npm view @starkscan/mcp@latest version --registry https://registry.npmjs.org)"

Codex setup

codex mcp add starkscan \
  --env STARKSCAN_API_KEY=$STARKSCAN_API_KEY \
  --env STARKSCAN_CHAIN=$STARKSCAN_CHAIN \
  -- npx -y "@starkscan/mcp@${STARKSCAN_MCP_VERSION}"

Useful starter tools for Starkscan agent workflows:

• status
• block_detail
• block_transactions
• token_total_supply
• token_balance_of
• token_transfers

Common agent mistakes

• search 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.
• wallet_asset_discovery returns candidate evidence and coverage, never balances.
• wallet_state verifies a bounded candidate set at one immutable block hash. Use require_complete for wallet home screens so any failed value fails visibly.
• The retired address_token_holdings tool is no longer advertised and fails without returning indexed holdings data.

Claude Code setup

claude mcp add --scope project --transport stdio \
  --env 'STARKSCAN_API_KEY=${STARKSCAN_API_KEY}' \
  --env STARKSCAN_CHAIN=$STARKSCAN_CHAIN \
  starkscan -- npx -y "@starkscan/mcp@${STARKSCAN_MCP_VERSION}"

Check that Claude Code sees it:

claude mcp list

Hosted MCP transport

Starkscan also exposes a native HTTP MCP endpoint at:

• https://api.starkscan.co/mcp on the API domain
• {appBaseUrl}/api/mcp on an app-origin deployment such as a preview host

Do not append another /api when STARKSCAN_BASE_URL already ends with /api, and do not set STARKSCAN_BASE_URL to the full /mcp URL. The npm launcher and CLI use the API-domain shape by default.

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 https://api.starkscan.co/mcp or POST {appBaseUrl}/api/mcp accepts one JSON-RPC message per request
• hosted MCP requests require Accept: application/json, text/event-stream
• requests after initialize require MCP-Protocol-Version: 2025-11-25; include it on scripted calls for consistent behavior
• inline JSON-RPC responses return as application/json
• JSON-RPC notifications return 202 Accepted without a response body
• GET requires Accept: text/event-stream; when that header is present today it returns 405 Method Not Allowed because SSE streams are not enabled
• stdio MCP frames are newline-delimited JSON-RPC messages; send one JSON object per line and keep each frame at or below the 1 MiB content cap

Smoke-test the remote MCP path

This direct smoke uses API-key auth because that is the same external key model as the REST, CLI, and launcher examples. OAuth-enabled hosted MCP deployments also accept Authorization: Bearer <token> with a Starkscan MCP resource/audience claim; resource metadata is served from /.well-known/oauth-protected-resource when OAuth metadata is configured.

curl -sS -X POST "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/mcp" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

This single-request smoke validates API-key auth, the required MCP HTTP headers, and a tools/list JSON-RPC response. For a full client session, use the MCP launcher or a real MCP client; they send initialize and notifications/initialized before tool calls.

• tools/list

When not to start with MCP

• Use the REST API for direct service integrations.
• Use the SDK for typed application code.
• Use the CLI when you need explicit commands and local exports.
• Stay in the explorer app when the job is visual investigation rather than tool-calling.