MCP Server
Use the Allium MCP server to run Explorer queries from agent workflows.
MCP Server
Run Allium Explorer queries from LLM agents using the Model Context Protocol (MCP).
Allium’s MCP server (mcp.allium.so
) implements Anthropic’s Model Context Protocol (MCP) to enable large language model agents to call Allium Explorer as a tool. This lets you integrate Allium’s blockchain data queries into AI-powered workflows. Agents can execute saved Explorer queries by ID and retrieve results in real time via standardized JSON tool calls, without needing to manually hit REST endpoints.
Running Saved Explorer Queries via MCP
Agents interact with the MCP server by invoking the explorer_run_query
tool. This tool executes a saved SQL query (identified by its unique query_id
) and returns the query results. The typical flow is:
- Save an Explorer Query: In the Allium Explorer interface, create and save your SQL query to obtain its
query_id
(each saved query has a unique ID). - Connect with API Key: Point your agent’s MCP client to
https://mcp.allium.so
and include your Allium API key (see Authentication below). - Call
explorer_run_query
: Invoke the MCP methodtools/call
withname: "explorer_run_query"
and supply thequery_id
. If the query is parameterized, include aparameters
object with the required values (this is optional if your query has no placeholders). - Receive Results: The MCP server will run the query and respond with the results embedded in the tool’s output. The agent can then parse the returned JSON string and use the data in its reasoning or response.
For example, an MCP request to run a saved query might look like this:
In the above JSON, replace <YOUR_QUERY_ID>
with the ID of your saved query. If the query requires parameters, add a "parameters"
field under "arguments"
(as shown in the comment) with the appropriate key-value pairs for your query.
Authentication
All requests to the Allium MCP server must include your API key for authorization. Provide your API key in the HTTP header X-API-KEY
when establishing the MCP connection or making requests. You can obtain an API key from the Allium Explorer interface (via Settings or the Explorer API page). Without a valid API key, the MCP server will reject incoming tool calls.
Response Format
The MCP server returns the query output in a JSON payload, delivered as a string inside the tool’s response. After calling explorer_run_query
, the result will be in the content.text
field of the MCP response. For example, a response might look like:
The value of content.text
is a JSON string containing the query results and metadata. In this example, the string (when parsed as JSON) includes the executed SQL (sql
), the result rows under data
(here a list of objects with a count
field), column definitions in meta.columns
, and a timestamp (queried_at
). Your agent should parse this JSON string to access the actual data. By default, results are limited to 250,000 rows per query (you can set a lower row limit via the API if needed).
Agent Integration Example
The Allium MCP server is compatible with agent frameworks that support MCP (e.g. LangGraph, LangChain with MCP adapter, or streamable-http clients). For instance, using LangGraph you can register the Allium Explorer MCP tool via configuration or code. Below is a sample configuration snippet in JSON for adding the explorer_run_query
tool to your agent:
In this configuration, the agent will connect to the Allium MCP server at mcp.allium.so
with the provided API key and load the explorer_run_query
tool. Once loaded, the agent can call Explorer queries by using this tool in its prompts or plans. The tool invocation and response are handled through MCP, so the agent receives structured data (as shown above) which it can parse and utilize in its reasoning.
Note: If you are using a custom MCP client or LangChain’s MCP adapter, ensure you initialize the MCP connection to https://mcp.allium.so
and include the X-API-KEY
header. The explorer_run_query
tool will be discoverable via the MCP server’s tools/list
and ready to use in your agent’s tool set.
MCP Server Configuration Example
If you’re managing your own MCP client or running agents via a runtime like mcp-agent
or mcp-remote
, you can configure the Allium MCP server as follows:
This example sets up an MCP client named allium-mcp
using mcp-remote
. It authenticates with the Allium MCP server using an environment variable API_KEY
. Replace the placeholder with your actual Allium API key. This allows the agent runtime to stream tool calls to Allium securely and without manual key injection.
See Also
- Saved Queries: Learn how to save queries in the Explorer UI and obtain a query ID in the Query Runner documentation (this is required to use
explorer_run_query
). - Explorer API Reference: For details on the underlying REST endpoints (running queries via API, retrieving results, etc.), see the Explorer API Reference. This can provide additional context on query runs and available parameters when using the MCP tool.