Blockscout MCP Server

Instructions

Implementation Reference

• blockscout_mcp_server/tools/chains/get_chains_list.py:15-77 (handler)

  Main handler function that fetches the list of supported chains from cache or Chainscout API, constructs ChainInfo objects, and returns a ToolResponse.

  @log_tool_invocation
  async def get_chains_list(ctx: Context) -> ToolResponse[list[ChainInfo]]:
      """
      Get the list of known blockchain chains with their IDs.
      Useful for getting a chain ID when the chain name is known. This information can be used in other tools that require a chain ID to request information.
      """  # noqa: E501
      api_path = "/api/chains"
  
      await report_and_log_progress(
          ctx,
          progress=0.0,
          total=1.0,
          message="Fetching chains list from Chainscout...",
      )
  
      chains = chains_list_cache.get_if_fresh()
      from_cache = True
  
      if chains is None:
          from_cache = False
          async with chains_list_cache.lock:
              chains = chains_list_cache.get_if_fresh()
              if chains is None:
                  response_data = await make_chainscout_request(api_path=api_path)
  
                  chains = []
                  if isinstance(response_data, dict):
                      filtered: dict[str, dict] = {}
                      url_map: dict[str, str] = {}
                      for chain_id, chain in response_data.items():
                          if not isinstance(chain, dict):
                              continue
                          url = find_blockscout_url(chain)
                          if url:
                              filtered[chain_id] = chain
                              url_map[chain_id] = url
  
                      await chain_cache.bulk_set(url_map)
  
                      for chain_id, chain in filtered.items():
                          if chain.get("name"):
                              chains.append(
                                  ChainInfo(
                                      name=chain["name"],
                                      chain_id=chain_id,
                                      # Fields follow the Chainscout API schema (isTestnet, native_currency)
                                      is_testnet=chain.get("isTestnet", False),
                                      native_currency=chain.get("native_currency"),
                                      ecosystem=chain.get("ecosystem"),
                                      settlement_layer_chain_id=chain.get("settlementLayerChainId"),
                                  )
                              )
  
                      chains_list_cache.store_snapshot(chains)
  
      await report_and_log_progress(
          ctx,
          progress=1.0,
          total=1.0,
          message="Successfully fetched chains list." if not from_cache else "Chains list returned from cache.",
      )
  
      return build_tool_response(data=chains or [])

• blockscout_mcp_server/models.py:44-58 (schema)

  Pydantic model defining the structure of ChainInfo returned by the tool.

  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.",
      )

• blockscout_mcp_server/server.py:213-216 (registration)

  Registration of the get_chains_list tool with the FastMCP server instance.

  mcp.tool(
      structured_output=False,
      annotations=create_tool_annotations("Direct Blockscout API Call"),
  )(direct_api_call)

• blockscout_mcp_server/models.py:384-410 (schema)

  Generic Pydantic model for ToolResponse[list[ChainInfo]] used as the return type of the handler.

  class ToolResponse(BaseModel, Generic[T]):
      """A standardized, structured response for all MCP tools, generic over the data payload type."""
  
      data: T = Field(description="The main data payload of the tool's response.")
  
      data_description: list[str] | None = Field(
          None,
          description="A list of notes explaining the structure, fields, or conventions of the 'data' payload.",
      )
  
      notes: list[str] | None = Field(
          None,
          description=(
              "A list of important contextual notes, such as warnings about data truncation or data quality issues."
          ),
      )
  
      instructions: list[str] | None = Field(
          None,
          description="A list of suggested follow-up actions or instructions for the LLM to plan its next steps.",
      )
  
      pagination: PaginationInfo | None = Field(
          None,
          description="Pagination information, present only if the 'data' is a single page of a larger result set.",
      )

• blockscout_mcp_server/tools/chains/get_chains_list.py:4-11 (helper)

  Imports of helper functions and caches used in the get_chains_list handler, such as chains_list_cache for caching the response.

  from blockscout_mcp_server.tools.common import (
      build_tool_response,
      chain_cache,
      chains_list_cache,
      find_blockscout_url,
      make_chainscout_request,
      report_and_log_progress,
  )