Building a Solana Program Inspector with MCP

TL;DR

Solana programs are black boxes once deployed. The binary sits on-chain, accounts accumulate state, and transactions flow through instructions. Understanding what a program does, what state it holds, and how it behaves requires piecing together information from IDLs, account data, transaction history, and program logs. A Solana Program Inspector built with custom MCP server development gives AI agents the tools to open that black box, deserialize every account, trace every transaction, and explain program behavior in plain language.

This post is a hands-on tutorial for building a Program Inspector MCP server. By the end, you will have an MCP server that can load any Anchor program’s IDL, deserialize its accounts, parse its transaction history, and surface insights about program usage and state.

A Program Inspector answers questions that developers, auditors, and operators ask constantly. What accounts does this program own? What is the current state of a specific vault? How many users have interacted with this program in the last 24 hours? What instructions are being called most frequently? Are there any accounts in an unexpected state?

Without an inspector, answering these questions requires writing custom scripts, running RPC queries, and manually deserializing binary data. With an MCP-powered inspector, an AI agent can answer all of them through structured tool calls.

The first capability your inspector needs is IDL loading. Anchor programs store their IDL on-chain at a deterministic address derived from the program ID. Your MCP server should support loading IDLs from three sources: on-chain (fetch from the IDL account), local file (for development), and URL (for programs that publish their IDL via HTTP).

Once loaded, the IDL becomes the Rosetta Stone for everything else the inspector does. Parse it into an internal representation that maps discriminators to account types, instruction names to their argument schemas, and error codes to human-readable messages. Store the parsed IDL in memory so subsequent tool calls do not need to re-fetch it.

Define an MCP tool called load_program that takes a program ID and an optional IDL source, loads the IDL, and returns a summary: program name, number of instructions, number of account types, number of error definitions, and the program’s deployment status (upgradeable or frozen, upgrade authority, last deployment slot).

With the IDL loaded, your inspector can deserialize any account owned by the program. Define an inspect_account tool that takes an account address, fetches the raw data from the RPC, reads the 8-byte discriminator to identify the account type, and deserializes the remaining bytes according to the IDL’s type definition.

The output should include the account type name, all fields with their values (formatted appropriately: public keys as base58, timestamps as ISO dates, token amounts with decimal adjustment), metadata (owner, lamports, data length, rent epoch), and any derived information (for example, if the account contains a vault with a deposit_cap and current_deposits, include a utilization_percentage field).

Define a list_accounts tool that uses getProgramAccounts to find all accounts of a specific type. This is powerful for getting a bird’s eye view of program state. How many vaults exist? How many user positions are open? What is the distribution of account states? The tool should support filtering (by account type, by field value) and pagination (program accounts can number in the thousands).

The inspector’s transaction analysis capability turns raw transaction data into structured, readable summaries. Define a get_program_transactions tool that fetches recent transactions involving the program and decodes each one.

For each transaction, decode the instruction data using the IDL to identify which instruction was called and what arguments were passed. Parse the program logs to extract custom log messages, CPI calls, and compute unit consumption. Identify the signer and any notable accounts involved. Return a structured summary: instruction name, arguments, accounts, result (success or failure with decoded error), compute units used, and any events emitted.

Define a get_instruction_stats tool that aggregates transaction data: how many times each instruction has been called in a given time period, success and failure rates per instruction, average compute units per instruction, and the most active signers. This gives operators and developers a quick health check on program usage.

The most valuable inspector capability is state analysis. Define an analyze_state tool that examines all accounts of a given type and surfaces insights. For a vault program, this might include total value locked across all vaults, number of active versus paused versus closed vaults, vaults approaching their deposit cap, vaults with unusual configurations (extremely high fees, single-user vaults, vaults with no recent activity), and any accounts with state inconsistencies (balances that do not sum correctly, timestamps in the future, references to non-existent accounts).

This kind of analysis is particularly valuable for auditors reviewing a program before or after deployment. An auditor can ask the agent to analyze all account state and flag anything that looks unusual, and the inspector will systematically check every account against expected invariants.

MCP prompts encode expert knowledge about how to inspect specific types of programs. Define prompt templates for common inspection scenarios.

Security review prompt. Guide the agent through a security-focused inspection: check upgrade authority (who can upgrade the program?), review access control patterns (which instructions require which signers?), verify PDA seed patterns (are seeds unique enough to prevent collisions?), check for missing close account implementations (can accounts be reclaimed?), and review CPI patterns (does the program make cross-program invocations safely?).

Operational health check prompt. Guide the agent through an operational review: check program usage trends (increasing, stable, declining?), review error rates by instruction, identify any accounts in error states, verify that administrative accounts (authorities, treasuries) are correctly configured, and check that fee collection is working as expected.

Migration readiness prompt. For teams planning a program upgrade, guide the agent through checking whether existing accounts are compatible with the new IDL, identifying accounts that need migration, estimating the number of transactions required for migration, and flagging any breaking changes that affect downstream integrations.

A production inspector needs caching (getProgramAccounts is expensive, cache results with TTL), rate limiting (protect your RPC endpoints from excessive queries), multi-network support (inspect the same program across devnet, testnet, and mainnet), and error handling (gracefully handle programs without IDLs, accounts with corrupted data, and RPC timeouts). Add these incrementally. Start with basic functionality and add production hardening as usage grows.

A Program Inspector is one of the most immediately useful MCP servers you can build for Solana development. It turns opaque on-chain state into structured, queryable data that AI agents can reason about. Whether you are debugging a failing test, auditing a deployed program, or monitoring program health in production, the inspector gives your agent the eyes it needs to understand what is happening on-chain.

Exo Technologies builds custom MCP server development tools for Solana teams, including Program Inspectors, deployment managers, and full-stack development assistants. If you want AI agents that understand your Solana programs as well as your team does, contact [email protected].