Starknetjs MCP

[tabaktoni]

RFC: Official MCP Server for starknet.js (@starknet-io/starknet-mcp)

Status: Draft Proposal
Date: February 2026

---

Summary

This proposal recommends creating an official MCP (Model Context Protocol) server as a companion package to starknet.js. The package would expose core starknet.js capabilities as MCP tools, enabling AI agents and LLM-powered applications to read from and write to Starknet without needing to write integration code.

The server would be published as a separate npm package under the starknet-io org, using starknet as a peer dependency. It does not modify the core SDK.

@starknet-io/starknet.js    ← core SDK (unchanged)
@starknet-io/starknet-mcp   ← MCP server, imports starknet.js as peer dep

Motivation

The AI agent ecosystem is rapidly adopting MCP as the standard protocol for tool integration. Claude, OpenAI, Cursor, Windsurf, and other major agent frameworks now support MCP servers natively.

Without an official server, Starknet agent integrations rely on community wrappers with varying quality and maintenance. The starknet-agentic project has demonstrated demand by building a community MCP server around starknet.js — an official package from starknet-io would provide a trusted, canonical integration point that stays in sync with SDK releases.

Why a separate package (not in starknet.js core):

• Different dependency graph — MCP servers need @modelcontextprotocol/sdk and transport layers
• Different release cadence — tool surface may evolve independently of the SDK
• Different audience — SDK users write code; MCP users are agent runtimes consuming tools
• starknet.js stays a library; the MCP server is a runnable process

Tool Surface Area

Tools are organized into three categories. The design principle: expose what an agent needs to reason about and act on Starknet, not the entire SDK API.

Read Tools (Provider-level, no account required)

Tool	Description	Key Parameters
get_balance	Token balance for an address (human-readable)	address, token_address? (defaults ETH)
get_block	Block by number, hash, or latest	block_id? (defaults latest)
call_contract	Read-only contract call	contract_address, entrypoint, calldata, abi?
get_transaction	Transaction by hash with status	tx_hash
get_transaction_receipt	Detailed receipt with parsed events	tx_hash
estimate_fee	Estimate fee for call(s)	calls[]
get_nonce	Current nonce for an address	address
get_class_at	Contract ABI at an address	contract_address

Write Tools (Account-level, requires configured account)

Tool	Description	Key Parameters
execute	Execute one or more calls (native multicall)	calls[] (contract, entrypoint, calldata)
deploy_account	Deploy a new account contract	class_hash, constructor_calldata, salt
declare_and_deploy	Declare class + deploy instance	contract, constructor_args
sign_message	Off-chain typed data signing (SNIP-12)	typed_data, domain

Write tools are not registered if no account is configured. Safe by default.

Utility Tools (local computation, no chain interaction)

Tool	Description	Key Parameters
encode_calldata	Encode human-readable args → calldata via ABI	abi, entrypoint, args
decode_events	Parse raw event data using ABI	events[], abi
resolve_address	StarknetID name ↔ address resolution	name or address
format_units	Raw value → human-readable (wei → ETH)	value, decimals
parse_units	Human-readable → raw value (ETH → wei)	value, decimals
get_chain_id	Return current chain ID	(none)

Key Feature: ABI-Aware Contract Interaction

The most differentiating feature — agents work with human-readable arguments instead of raw felt arrays:

1. Agent calls get_class_at to discover a contract's ABI
2. Agent calls execute with: { contract: "0x...", entrypoint: "transfer", args: { recipient: "0x...", amount: "1.5" } }
3. MCP server internally resolves the ABI, encodes calldata via CallData.compile(), handles unit conversion, estimates fees, and executes

This dramatically lowers the barrier for agents to interact with arbitrary Starknet contracts without deep protocol knowledge.

Configuration

Minimal config requires only an RPC URL. Write tools activate when account credentials are provided.

Variable	Required	Default	Description
STARKNET_RPC_URL	Yes	—	JSON-RPC endpoint
STARKNET_NETWORK	No	mainnet	Network (mainnet, sepolia)
STARKNET_ACCOUNT_ADDRESS	No	—	Enables write tools
STARKNET_PRIVATE_KEY	No	—	Enables write tools
STARKNET_MCP_TRANSPORT	No	stdio	Transport: stdio or http

Scope Boundaries

In scope: Core chain read/write primitives, calldata encoding/decoding, StarknetID resolution, fee estimation, ABI caching.

Explicitly out of scope:

• DeFi-specific tools (swaps, staking, LP) → belongs in higher-level skill packs
• Wallet generation / key management → security-sensitive, external tooling
• Block explorer / indexing → dedicated services
• Persistent state between calls → agent framework's responsibility
• Cross-chain / L1↔L2 messaging → separate tooling

Design principle: This server exposes the same primitives as starknet.js's Provider and Account classes. Higher-level abstractions should be separate MCP servers or skill packs that build on top of this one.

Ecosystem Positioning

┌─────────────────────────────────────────────────────────────┐
│  Agent Frameworks (Claude, Daydreams, Lucid, OpenClaw...)   │
├─────────────────────────────────────────────────────────────┤
│  Skill Packs / High-level MCP (starknet-agentic, DeFi...)  │
├─────────────────────────────────────────────────────────────┤
│  @starknet-io/starknet-mcp  ← THIS PROPOSAL                │
├─────────────────────────────────────────────────────────────┤
│  @starknet-io/starknet.js (core SDK)                        │
├─────────────────────────────────────────────────────────────┤
│  Starknet L2                                                │
└─────────────────────────────────────────────────────────────┘

Community projects like starknet-agentic benefit by depending on this for low-level ops instead of maintaining their own wrappers — they can focus on DeFi skills, identity workflows, and agent-to-agent protocols.

Implementation Plan

Phase 1 — Read tools + Utilities: All read tools, all utility tools, stdio transport, JSON Schema tool descriptions. Safe to ship fast.

Phase 2 — Write tools + ABI cache: execute, deploy_account, declare_and_deploy, sign_message. In-memory ABI cache for transparent calldata encoding.

Phase 3 — HTTP transport + Hardening: HTTP/SSE transport, rate limiting, session key support (Cartridge Controller), telemetry hooks.

Open Questions

1. Repo location — Separate repo (starknet-io/starknet-mcp) or monorepo subfolder within starknet.js?
2. Naming — @starknet-io/starknet-mcp vs @starknet-io/starknet-js-mcp vs other?
3. RPC version pinning — Pin to specific RPC spec version, or follow starknet.js's supported range?
4. Session keys — Include Cartridge Controller session key integration in Phase 2 or defer?
5. Community coordination — Reach out to starknet-agentic maintainers to coordinate scope?
6. Testing — Unit tests with mocked RPC, integration tests against Sepolia, or both?

---

Would love feedback on the tool surface area, scope boundaries, and overall approach. What's missing? What should be cut?

[tabaktoni]

@0xlny @penovicp