​
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:

  1. 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).
  2. Connect with API Key: Point your agent’s MCP client to https://mcp.allium.so and include your Allium API key (see Authentication below).
  3. Call explorer_run_query: Invoke the MCP method tools/call with name: "explorer_run_query" and supply the query_id. If the query is parameterized, include a parameters object with the required values (this is optional if your query has no placeholders).
  4. 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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "explorer_run_query",
    "arguments": {
      "query_id": "<YOUR_QUERY_ID>"
      /* "parameters": { "param_name": "value", ... } // optional */
    }
  }
}

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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": {
      "text": "{\"sql\":\"SELECT ...\",\"data\":[{\"count\": 123}],\"meta\":{\"columns\":[{\"name\":\"count\",\"data_type\":\"NUMBER\"}]},\"queried_at\":\"2025-06-03T07:00:00Z\"}"
    }
  }
}

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:

{
  "tools": [
    {
      "name": "explorer_run_query",
      "server": "https://mcp.allium.so",
      "headers": {
        "X-API-KEY": "<YOUR_API_KEY>"
      }
    }
  ]
}

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:

"mcpServers": {
  "allium-mcp": {
    "command": "npx",
    "args": [
      "mcp-remote",
      "https://mcp.allium.so/",
      "--header",
      "X-API-KEY:${API_KEY}"
    ],
    "env": {
      "API_KEY": "<Your API key here>"
    }
  }
}

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.