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