MCP Explained Part 8: Server Instructions

TL;DR: The Blockscout MCP Server delivers its operational guidance to AI agents in two synchronized ways - through the standard MCP instructions field during initialization and through a dedicated initialization tool, __unlock_blockchain_analysis__.

This dual system ensures that both compliant and partially compliant MCP hosts receive the same essential context before reasoning begins.

Dual Instruction System

The design of Blockscout MCP Server instructions evolved through a mixture of protocol compliance and empirical observation.

According to the MCP specification, every server may provide an instructions field during initialization. These initialization-time instructions are meant to teach the AI agent how to interact with the server’s tools before any reasoning begins.

This feature was kept and is fully used in the Blockscout MCP server: it ensures that hosts which correctly process server-level instructions (such as future MCP clients or standardized gateways) receive the full operational context immediately upon connection.

However, testing revealed that many existing MCP hosts - especially general-purpose ones like Claude Desktop - ignored the initialization instructions field. The agent started tool calls without internalizing any operational rules. To address this limitation, an additional mechanism was introduced: a dedicated initialization tool.

At first, a tool named __get_instructions__ was implemented to allow agents to retrieve instructions manually, but this approach proved ineffective. Agents tended to treat it as optional reading material rather than a required initialization step.

To enforce a proper startup sequence, the tool was renamed to __unlock_blockchain_analysis__, creating a stronger semantic signal. The verb unlock aligns with the familiar “setup → execute” pattern found in code and documentation, prompting the model to view the call as mandatory.

In practice, this change transformed agent behavior: most models now consistently call __unlock_blockchain_analysis__ before using any analytical tools.

Thus, both instruction paths remain active:

• The initialization-time instructions field provides early guidance for clients that respect the MCP specification.
• The __unlock_blockchain_analysis__ tool guarantees that even clients which ignore server-level instructions still obtain the same information before performing blockchain analysis.

What the Instructions Include

The server instructions define the entire operational philosophy of the Blockscout MCP server — how to reason about chain selection, pagination, time filters, and efficiency.

The main elements are:

• Chain selection guidance: every tool requires a chain_id. The instructions provide a default (1 for Ethereum Mainnet), explain how to call get_chains_list when the target chain is unclear, and list the most popular chain IDs.
• Pagination rules: the agent must always use the exact next-call template provided in pagination.next_call and continue iterating when comprehensive data is requested.
• Time-based query rules: for queries involving specific dates or periods, tools supporting age_from / age_toshould be used first (e.g., get_transactions_by_address), and further data should then be derived from those transactions.
• Block time estimation rules: when no native time filters exist, agents are instructed to estimate target blocks mathematically using adaptive sampling of block intervals (average block times, correction by local trends).
• Efficiency optimization rules: strategies to minimize redundant calls: combine estimation and sampling, recalibrate using fresh data, and avoid long sequential pagination.
• Binary search rules: for locating temporal boundaries (like a first or last transaction), the instructions prescribe a binary search approach instead of page-by-page iteration.
• Direct API call endpoints: a curated catalog of advanced Blockscout API paths accessible via direct_api_call, grouped by purpose (stats, tokens & NFTs, rollup messages, validator data, MUD worlds, etc.) so the agent can perform deeper analysis when standard tools do not cover a use case.