@starkscan/mcp

MCP launcher for connecting agent clients to Starkscan tools.

Release target: 0.3.0. This release carries the address-activity truth schema through the matching CLI and hosted MCP tool contract. Use the untagged command only after the live latest verifier passes; pin 0.3.0 for reproducible configs after that promotion.

Default command

npx -y @starkscan/mcp

Exact pin for unattended services:

npx -y @starkscan/[email protected]

Prerelease tags such as @beta are maintainer-directed test channels only. Normal users and agents should use the default package or the exact 0.3.0 pin above.

The published global binary name is starkscan-mcp, not mcp, to avoid colliding with unrelated MCP tools. Prefer the package-scoped npx command above for agent client configs.

With no arguments, the launcher runs:

starkscan mcp start --transport remote

It delegates to the exact matching @starkscan/cli package, which verifies and executes the prebuilt native Starkscan binary.

Environment

export STARKSCAN_API_KEY="<store this in your shell or MCP host 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"

The launcher defaults to https://api.starkscan.co; do not set STARKSCAN_BASE_URL for normal hosted production use. Keep API keys in the MCP host secret store or shell environment, not in committed config files.

Common commands

npx -y @starkscan/[email protected] print-config --transport remote
npx -y @starkscan/[email protected] tools
npx -y @starkscan/[email protected] doctor
npx -y @starkscan/[email protected] start --transport remote

For manual smoke checks only, you can replace the exact version with the untagged package. Keep saved MCP configs pinned when reproducibility matters.

print-config emits ready-to-paste snippets for Codex, Claude Code, Cursor, Claude Desktop, and Cline. Snippets use environment-variable placeholders, not secret values.

Codex setup

codex mcp add starkscan \
  --env 'STARKSCAN_API_KEY=${STARKSCAN_API_KEY}' \
  --env STARKSCAN_CHAIN=$STARKSCAN_CHAIN \
  -- npx -y @starkscan/[email protected]

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/[email protected]

What it exposes

• One-command MCP onboarding for local agent clients.
• Starkscan route tools through the hosted MCP transport.
• Shared API-key auth with REST, SDK, and CLI.
• Tool catalog discovery through the underlying CLI.
• Consistent request IDs for support/debug reports.

Starter tools for agent workflows:

• Bootstrap and discovery: status, search
• Blocks and transactions: block_detail, block_transactions, tx_detail
• Wallets: address_summary, address_activity, address_transactions, wallet_asset_discovery, wallet_state
• Token accounting: token_total_supply, token_balance_of, token_transfers
• Contract inspection: contract_verification, contract_entrypoints, contract_read
• Write preparation: contract_write_payload builds an unsigned payload for an external signer; it does not submit transactions

The hosted MCP transport is POST https://api.starkscan.co/mcp. It uses the 2025-11-25 MCP protocol headers, API-key auth, and JSON-RPC responses. For the complete tool list and arguments, see https://starkscan.co/docs/ai/mcp-tools-reference.

Trust boundary

This package is a local launcher. It asks @starkscan/cli to verify and execute the prebuilt native Starkscan binary on your machine. Install it only from the official npm package, keep API keys in your MCP host secret store, and do not run it with elevated privileges.

Any operation beyond read-only API/MCP access must require an explicit client-side opt-in before it is added to this launcher. The current tool catalog includes one unsigned write-payload builder; it builds a payload for a signer and is not a transaction submission path by itself.

Trust and safety

• npm package: https://www.npmjs.com/package/@starkscan/mcp
• MCP docs: https://starkscan.co/docs/ai/mcp-quickstart
• API key setup: https://starkscan.co/api-key
• Package trust: https://starkscan.co/docs/build/package-trust
• Machine-readable launch matrix: https://starkscan.co/public-client-surface-matrix.json
• Socket signal: https://socket.dev/npm/package/@starkscan/mcp

Socket is an external package-risk signal, not a Starkscan security certificate. The public trust source is Starkscan docs because the canonical engineering repository is private. Package promotion also requires exact CLI dependency pinning, packaged-launcher smoke, npm Trusted Publishing/OIDC for CI publishes, and live MCP smoke proof.

Pinning and rollback

Use exact versions for agent configs and unattended services when reproducibility matters:

npx -y @starkscan/[email protected]

Release notes live in CHANGELOG.md. If a launcher release regresses, roll back by changing the client command back to the last known-good version and restarting the MCP host. Do not rotate API keys for a launcher binary regression unless there is evidence that a key was exposed.