Blockscout MCP Server

Instructions

Do not include query strings in ``endpoint_path``; pass all query parameters via
``query_params`` to avoid double-encoding.

**SUPPORTS PAGINATION**: If response includes 'pagination' field,
use the provided next_call to get additional pages.

Returns:
    ToolResponse[Any]: Must return ToolResponse[Any] (not ToolResponse[BaseModel])
    because specialized handlers can return lists or other types that don't inherit
    from BaseModel. The dispatcher system supports flexible data structures.

Implementation Reference

• blockscout_mcp_server/tools/direct_api/direct_api_call.py:20-114 (handler)

  Main execution logic for the 'direct_api_call' tool: resolves Blockscout URL, makes API request with pagination support, dispatches to specialized handlers if applicable, and returns structured ToolResponse.

  @log_tool_invocation
  async def direct_api_call(
      chain_id: Annotated[str, Field(description="The ID of the blockchain")],
      endpoint_path: Annotated[
          str,
          Field(
              description="The Blockscout API path to call (e.g., '/api/v2/stats'); do not include query strings.",
          ),
      ],
      ctx: Context,
      query_params: Annotated[
          dict[str, Any] | None,
          Field(description="Optional query parameters forwarded to the Blockscout API."),
      ] = None,
      cursor: Annotated[
          str | None,
          Field(description="The pagination cursor from a previous response to get the next page of results."),
      ] = None,
  ) -> ToolResponse[Any]:
      """Call a raw Blockscout API endpoint for advanced or chain-specific data.
  
      Do not include query strings in ``endpoint_path``; pass all query parameters via
      ``query_params`` to avoid double-encoding.
  
      **SUPPORTS PAGINATION**: If response includes 'pagination' field,
      use the provided next_call to get additional pages.
  
      Returns:
          ToolResponse[Any]: Must return ToolResponse[Any] (not ToolResponse[BaseModel])
          because specialized handlers can return lists or other types that don't inherit
          from BaseModel. The dispatcher system supports flexible data structures.
      """
      await report_and_log_progress(
          ctx,
          progress=0.0,
          total=2.0,
          message=f"Resolving Blockscout URL for chain {chain_id}...",
      )
      base_url = await get_blockscout_base_url(chain_id)
      if endpoint_path != "/" and endpoint_path.endswith("/"):
          endpoint_path = endpoint_path.rstrip("/")
      if "?" in endpoint_path:
          raise ValueError("Do not include query parameters in endpoint_path. Use query_params instead.")
  
      params = dict(query_params) if query_params else {}
      apply_cursor_to_params(cursor, params)
  
      await report_and_log_progress(
          ctx,
          progress=1.0,
          total=2.0,
          message="Fetching data from Blockscout API...",
      )
      response_json = await make_blockscout_request(base_url=base_url, api_path=endpoint_path, params=params)
  
      handler_response = await dispatcher.dispatch(
          endpoint_path=endpoint_path,
          query_params=query_params,
          response_json=response_json,
          chain_id=chain_id,
          base_url=base_url,
          ctx=ctx,
      )
      if handler_response is not None:
          await report_and_log_progress(
              ctx,
              progress=2.0,
              total=2.0,
              message="Successfully fetched data.",
          )
          return handler_response
  
      pagination = None
      next_page_params = response_json.get("next_page_params")
      if next_page_params:
          next_cursor = encode_cursor(next_page_params)
          next_call_params = {
              "chain_id": chain_id,
              "endpoint_path": endpoint_path,
              "cursor": next_cursor,
          }
          if query_params:
              next_call_params["query_params"] = query_params
          pagination = PaginationInfo(next_call=NextCallInfo(tool_name="direct_api_call", params=next_call_params))
  
      await report_and_log_progress(
          ctx,
          progress=2.0,
          total=2.0,
          message="Successfully fetched data.",
      )
  
      data = DirectApiData.model_validate(response_json)
      return build_tool_response(data=data, pagination=pagination)

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

  Registers the 'direct_api_call' 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/tools/direct_api/dispatcher.py:36-59 (helper)

  Dispatcher utility that routes API responses to registered specialized handlers based on endpoint path regex matching.

  async def dispatch(
      endpoint_path: str,
      **kwargs: Any,
  ) -> Any | None:
      """Find and execute the first matching handler for the given endpoint path.
  
      Args:
          endpoint_path: The API path that was requested.
          **kwargs: Additional context forwarded to the handler.
  
      Note: precedence follows registration order. Keep regex patterns disjoint or
      register the most specific handler first when overlap is unavoidable.
  
      Returns:
          Any | None: Must return Any (not ToolResponse[BaseModel]) because some handlers
          can return lists or other types that don't inherit from BaseModel. The handler
          is responsible for returning properly structured ToolResponse objects.
      """
      for path_regex, handler in HANDLER_REGISTRY:
          match = path_regex.fullmatch(endpoint_path)
          if match:
              return await handler(match=match, **kwargs)
      return None

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

  Generic output schema used by direct_api_call and other tools for standardized responses including data, notes, instructions, and pagination.

  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/models.py:70-75 (helper)

  Pydantic model for validating and wrapping raw direct API response data, allowing extra fields.

  class DirectApiData(BaseModel):
      """Generic container for direct API responses."""
  
      model_config = ConfigDict(extra="allow")