MCP Explained Part 7: Direct API Calls

TL;DR: The direct_api_call tool lets LLM agents access any Blockscout API endpoint not already covered by existing MCP tools. It extends the MCP server’s flexibility without increasing the number of tools or context size.

The tool preserves all core optimization principles: safe pagination, compact context, and specialized response handling when needed.

Rationale

As explained in Part 1: Introduction, every MCP tool adds to the model’s context cost. Keeping the toolset small is essential, but this limits the range of available API endpoints. Some advanced analyses - for example, rollup batch inspection or cross-chain message tracking - require access to endpoints not included in the predefined list.

To cover these cases without expanding the toolset, the MCP server introduces a universal tool that can call any supported Blockscout API endpoint directly, while still following all the context and pagination optimizations described in Part 2: Optimizations.

Endpoint Discovery

The list of available API endpoints is provided in two ways:

1: Primary curated list

A short list of common and chain-specific endpoints is shared through the MCP instructions (or, for clients that do not process server-level instructions, during the call to the MCP tool __unlock_blockchain_analysis__).

Each entry includes the endpoint path and a brief description, e.g. /api/v2/tokens/{token_contract_address}/instances – “Get all NFT instances for a given token contract.”

Since the LLM already understands blockchain domain concepts through the MCP server’s initialization process - specifically, by absorbing the server-level instructions and the descriptions of all available MCP tools - it enters a state where it can interpret short API endpoint descriptions correctly.

In this context, concise phrases are sufficient for the model to decide when an endpoint is relevant and how to substitute parameter templates with actual values such as addresses, transaction hashes, or block numbers.

2: Context-relevant hints

Some tools include follow-up suggestions in their instructions field.

For example, get_address_info may return:“Use direct_api_call with endpoint /api/v2/proxy/account-abstraction/accounts/0x... to get Account Abstraction info.”

This helps the model explore deeper layers only when contextually relevant.

Design Principles

When exposing new API endpoints through direct_api_call, three rules apply:

1. Must not duplicate functionality already provided by existing, specific MCP tools. This eliminates “tool selection confusion” for the AI and ensures that the new MCP tool serves a complementary role rather than creating redundancy.
2. Must have relatively simple input parameters, making it easier for LLMs to construct valid calls. The LLM substitutes any path parameters (e.g., {account_address}) directly into the endpoint URL string.
3. Must not return excessively large or complex raw data payloads to prevent LLM context overflow and to maintain the server’s overall context optimization strategy.

This keeps the direct_api_call tool complementary - expanding coverage without introducing redundancy.

Tool Parameters

The tool accepts the following parameters:

• chain_id - target blockchain network ID.
• endpoint_path - the API path to call.
• query_params - additional query parameters not part of the path.
• cursor - a Base64URL-encoded token for pagination continuation.

If cursor is provided, the server decodes it and merges the pagination parameters with query_params. When the Blockscout API returns next_page_params, the server encodes them again in Base64URL, following the same opaque cursor strategy as other MCP tools (see Part 2: Optimizations).

Specialized Response Handling via Dispatcher

While the direct_api_call tool is designed to be a generic gateway, some endpoints benefit from specialized response processing to make their data more useful and context-friendly for LLM agents (e.g. getting logs emitted by account).

To accommodate this without creating new tools, direct_api_callimplements an internal dispatcher pattern.

• Dispatcher: This module contains logic to match an incoming endpoint_path to a specific handler function.
• Handlers: Each handler is responsible for transforming a raw JSON API response into a specific structured data model, applying logic like data truncation, field curation, and custom pagination.

If a matching handler is found, direct_api_call returns the rich, structured response from the handler. If no handler matches, it falls back to its default behavior of returning the raw, unprocessed JSON response.

This architecture allows for targeted enhancements while keeping the tool surface minimal and the system easily extensible.