Blockscout MCP Server

Instructions

All tools remain locked with a "Session Not Initialized" error until this
function is successfully called. Skipping this explicit initialization step
will cause all subsequent tool calls to fail.

MANDATORY FOR AI AGENTS: The returned instructions contain ESSENTIAL rules
that MUST govern ALL blockchain data interactions. Failure to integrate these
rules will result in incorrect data retrieval, tool failures and invalid
responses. Always apply these guidelines when planning queries, processing
responses or recommending blockchain actions.

COMPREHENSIVE DATA SOURCES: Provides an extensive catalog of specialized
blockchain endpoints to unlock sophisticated, multi-dimensional blockchain
investigations across all supported networks.

Implementation Reference

• blockscout_mcp_server/tools/initialization/unlock_blockchain_analysis.py:35-100 (handler)

  Core handler function implementing the __unlock_blockchain_analysis__ tool. Constructs InstructionsData from constants and returns a ToolResponse.

  @log_tool_invocation
  async def __unlock_blockchain_analysis__(ctx: Context) -> ToolResponse[InstructionsData]:
      """Unlocks access to other MCP tools.
  
      All tools remain locked with a "Session Not Initialized" error until this
      function is successfully called. Skipping this explicit initialization step
      will cause all subsequent tool calls to fail.
  
      MANDATORY FOR AI AGENTS: The returned instructions contain ESSENTIAL rules
      that MUST govern ALL blockchain data interactions. Failure to integrate these
      rules will result in incorrect data retrieval, tool failures and invalid
      responses. Always apply these guidelines when planning queries, processing
      responses or recommending blockchain actions.
  
      COMPREHENSIVE DATA SOURCES: Provides an extensive catalog of specialized
      blockchain endpoints to unlock sophisticated, multi-dimensional blockchain
      investigations across all supported networks.
      """
      # Report start of operation
      await report_and_log_progress(
          ctx,
          progress=0.0,
          total=1.0,
          message="Fetching server instructions...",
      )
  
      # Construct the structured data payload
      chain_id_guidance = ChainIdGuidance(
          rules=CHAIN_ID_RULES,
          recommended_chains=[ChainInfo(**chain) for chain in RECOMMENDED_CHAINS],
      )
  
      common_groups = []
      for group_data in DIRECT_API_CALL_ENDPOINT_LIST["common"]:
          endpoints = [DirectApiEndpoint(**endpoint) for endpoint in group_data["endpoints"]]
          common_groups.append(DirectApiCommonGroup(group=group_data["group"], endpoints=endpoints))
  
      specific_groups = []
      for group_data in DIRECT_API_CALL_ENDPOINT_LIST["specific"]:
          endpoints = [DirectApiEndpoint(**endpoint) for endpoint in group_data["endpoints"]]
          specific_groups.append(DirectApiSpecificGroup(chain_family=group_data["chain_family"], endpoints=endpoints))
  
      direct_api_endpoints = DirectApiEndpointList(common=common_groups, specific=specific_groups)
  
      instructions_data = InstructionsData(
          version=SERVER_VERSION,
          error_handling_rules=ERROR_HANDLING_RULES,
          chain_id_guidance=chain_id_guidance,
          pagination_rules=PAGINATION_RULES,
          time_based_query_rules=TIME_BASED_QUERY_RULES,
          block_time_estimation_rules=BLOCK_TIME_ESTIMATION_RULES,
          efficiency_optimization_rules=EFFICIENCY_OPTIMIZATION_RULES,
          binary_search_rules=BINARY_SEARCH_RULES,
          direct_api_call_rules=DIRECT_API_CALL_RULES,
          direct_api_endpoints=direct_api_endpoints,
      )
  
      # Report completion
      await report_and_log_progress(
          ctx,
          progress=1.0,
          total=1.0,
          message="Server instructions ready.",
      )
  
      return build_tool_response(data=instructions_data)

• blockscout_mcp_server/models.py:43-119 (schema)

  Pydantic models defining the structure of InstructionsData and supporting classes used in the tool's ToolResponse.

  # --- Model for __unlock_blockchain_analysis__ Data Payload ---
  class ChainInfo(BaseModel):
      """Represents a blockchain with its essential identifiers."""
  
      name: str = Field(description="The common name of the blockchain (e.g., 'Ethereum').")
      chain_id: str = Field(description="The unique identifier for the chain.")
      is_testnet: bool = Field(description="Indicates if the chain is a testnet.")
      native_currency: str | None = Field(description="The native currency symbol of the chain (e.g., 'ETH').")
      ecosystem: str | list[str] | None = Field(
          description="The ecosystem the chain belongs to, if applicable (e.g., 'Ethereum')."
      )
      settlement_layer_chain_id: str | None = Field(
          default=None,
          description="The L1 chain ID where this rollup settles, if applicable.",
      )
  
  
  # --- Model for __unlock_blockchain_analysis__ Data Payload ---
  class ChainIdGuidance(BaseModel):
      """A structured representation of chain ID guidance combining rules and recommendations."""
  
      rules: str = Field(description="Rules for chain ID selection and usage.")
      recommended_chains: list[ChainInfo] = Field(
          description="A list of popular chains with their names and IDs, useful for quick lookups."
      )
  
  
  class DirectApiData(BaseModel):
      """Generic container for direct API responses."""
  
      model_config = ConfigDict(extra="allow")
  
  
  class DirectApiEndpoint(BaseModel):
      """Represents a single direct API endpoint."""
  
      path: str = Field(description="The API endpoint path (e.g., '/api/v2/stats').")
      description: str = Field(description="A description of what this endpoint returns.")
  
  
  class DirectApiCommonGroup(BaseModel):
      """Represents a group of common endpoints available on all chains."""
  
      group: str = Field(description="The functional group name (e.g., 'Stats', 'Tokens & NFTs').")
      endpoints: list[DirectApiEndpoint] = Field(description="List of endpoints in this group.")
  
  
  class DirectApiSpecificGroup(BaseModel):
      """Represents a group of endpoints specific to certain chain families."""
  
      chain_family: str = Field(description="The chain family this group applies to (e.g., 'Arbitrum', 'Optimism').")
      endpoints: list[DirectApiEndpoint] = Field(description="List of chain-specific endpoints.")
  
  
  class DirectApiEndpointList(BaseModel):
      """Contains the complete curated list of endpoints for direct_api_call tool."""
  
      common: list[DirectApiCommonGroup] = Field(description="Endpoint groups available on all supported chains.")
      specific: list[DirectApiSpecificGroup] = Field(description="Endpoint groups specific to certain chain families.")
  
  
  class InstructionsData(BaseModel):
      """A structured representation of the server's operational instructions."""
  
      version: str = Field(description="The version of the Blockscout MCP server.")
      error_handling_rules: str = Field(description="Rules for handling network errors and retries.")
      chain_id_guidance: ChainIdGuidance = Field(description="Comprehensive guidance for chain ID selection and usage.")
      pagination_rules: str = Field(description="Rules for handling paginated responses and data retrieval.")
      time_based_query_rules: str = Field(description="Rules for executing time-based blockchain queries efficiently.")
      block_time_estimation_rules: str = Field(description="Rules for mathematical block time estimation and navigation.")
      efficiency_optimization_rules: str = Field(description="Rules for optimizing query strategies and performance.")
      binary_search_rules: str = Field(description="Rules for using binary search for historical blockchain data.")
      direct_api_call_rules: str = Field(description="Rules and guidance for using the direct_api_call tool.")
      direct_api_endpoints: "DirectApiEndpointList" = Field(
          description="Curated list of endpoints available for direct API calls."
      )

• blockscout_mcp_server/server.py:145-148 (registration)

  Registration of the __unlock_blockchain_analysis__ tool with the FastMCP server instance, including annotations.

  mcp.tool(
      structured_output=False,
      annotations=create_tool_annotations("Unlock Blockchain Analysis"),
  )(__unlock_blockchain_analysis__)