​
🚧 Welcome to the Allium MCP Server!

Allium MCP Server is currently in Beta. We are constantly improving our MCP Server and adding new features. If you have any feedback or suggestions, please reach out to us at support@allium.so or share your thoughts or suggestions via this feedback form.

​
🧠 Overview

The Allium MCP Server lets your agents query blockchain data using structured tool calls — no REST or custom glue code required. Agents can run saved Explorer queries, issue raw SQL, and introspect Allium schemas via the Model Context Protocol (MCP). Endpoint: https://mcp.allium.so

​
🛠 Available Tools

Allium’s MCP Server exposes the following tools:
Tool NameDescription
explorer_run_queryRun a saved Explorer query using its query_id. Supports parameterization.
explorer_run_sqlRun a raw SQL string directly against Allium’s production datasets.
explorer_search_schemasSemantic search across all schema docs. Returns relevant table IDs.
explorer_fetch_schemaFetch YAML schema metadata by table IDs (full table name, e.g. ethereum.raw.blocks).
💡 Schema IDs match full table names (e.g. ethereum.raw.token_transfers). Use search before fetching.

​
🔐 Authentication

All tools require an API key. Use the HTTP header: 
X-API-KEY: <your-api-key>
You can generate and manage your API keys here: 👉 https://app.allium.so/settings/api-keys

​
🔽 How to Use the Tools

​
1. Run Saved Queries (explorer_run_query)

To run a query you created in the Allium Explorer UI:
  1. Save the query to get its query_id
  2. Use the explorer_run_query tool:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "explorer_run_query",
    "arguments": {
      "query_id": "<YOUR_QUERY_ID>"
      // "parameters": { "param": "value" } // optional
    }
  }
}
Returns a JSON-encoded string in content.text with:
  • sql: the full query text
  • data: result rows
  • meta.columns: column names and types
  • queried_at: execution timestamp

​
2. Run Raw SQL (explorer_run_sql)

Use this for ad-hoc queries: 
{
  "name": "explorer_run_sql",
  "arguments": {
    "sql": "SELECT COUNT(*) FROM ethereum.raw.transactions"
  }
}
Supports up to 250,000 rows per query by default. Returns the same result format as explorer_run_query.

​
3. Explore Schemas

​
🔎 Search (explorer_search_schemas)

Find relevant tables: 
{
  "name": "explorer_search_schemas",
  "arguments": {
    "query": "erc20 token transfers"
  }
}
Returns: 
["ethereum.raw.token_transfers", "ethereum.unified.transfers", ...]

​
📄 Fetch Schema (explorer_fetch_schema)

Retrieve a table’s YAML schema: 
{
  "name": "explorer_fetch_schema",
  "arguments": {
    "id": "ethereum.raw.token_transfers"
  }
}
Returns: 
table: ethereum.raw.token_transfers
description: ERC20 token transfers on Ethereum mainnet
columns:
  - name: transaction_hash
    type: STRING
    description: Transaction hash
  - name: amount
    type: NUMBER
    description: Raw token amount (unadjusted)
  ...

​
⚙️ Agent Integration

​
LangGraph / LangChain

Register tools in your agent’s configuration: 
{
  "tools": [
    {
      "name": "explorer_run_query",
      "server": "https://mcp.allium.so",
      "headers": {
        "X-API-KEY": "<YOUR_API_KEY>"
      }
    },
    {
      "name": "explorer_run_sql",
      "server": "https://mcp.allium.so",
      "headers": {
        "X-API-KEY": "<YOUR_API_KEY>"
      }
    }
  ]
}
You can add explorer_fetch_schema and explorer_search_schemas the same way.

​
mcp-remote / Local CLI

If using streamable-http or other CLI-based setups: 
{
  "mcpServers": {
    "allium": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.allium.so",
        "--header",
        "X-API-KEY:${API_KEY}"
      ],
      "env": {
        "API_KEY": "<your-api-key>"
      }
    }
  }
}
This will enable local agent tool streaming with auth injected from env.

​
📦 Response Format

All query tools return a JSON-RPC result in this structure: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": {
      "text": "{"sql": "SELECT ...", "data": [...], "meta": {"columns": [...]}, "queried_at": "2025-07-01T00:00:00Z"}"
    }
  }
}
Parse the content.text string as JSON to extract:
  • sql: Full query string
  • data: List of result rows (objects)
  • meta.columns: Each column’s name + data type
  • queried_at: ISO timestamp

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