Introduction

We are happy to announce that in the last release we added full Model Context Protocol support to DipDup. Now you can run the MCP server alongside your DipDup project and interact with the indexer using natural language! In this tutorial we will connect the DipDup MCP server to AI assistants/models and explore a few examples of different levels of complexity. Still, this technology is very new and there are infinite ways to use it, so I hope this guide will inspire you to try something new.

MCP Explanation

The Model Context Protocol (MCP) is an open standard that describes a universal interface between LLMs and external systems. It allows AI models to discover and use functionality from applications without custom integrations for each tool.

Architecture

MCP works through a client-server architecture:

• MCP servers (like your DipDup indexer MCP server) expose functionality and data
• MCP clients (like GitHub Copilot in VS Code) connect to these servers to access their capabilities

There are three types of MCP primitives: resources allow to expose data and content, tools enable servers to expose executable functionality to clients, and prompts enable servers to define reusable prompt templates and workflows.

When an LLM interacts with MCP, it primarily uses Tools - callable functions with defined parameters that perform specific operations. Tools are the most widely supported MCP primitive across clients today. When you query an AI assistant with MCP support it:

• Adds to the LLM's context list of tools described in config and exposed through listed MCP servers
• Selects the appropriate tool based on your query
• Calls the tool with the necessary parameters
• Processes the returned data to answer your question

In the DipDup context, MCP creates a bridge between your blockchain indexer and AI assistants. This allows LLMs to understand your project's structure, query indexed data directly, and even initiate indexing operations through natural language commands - all without requiring you to build custom integrations for each AI tool.

Several LLM clients support MCP, including VS Code's GitHub Copilot (which we'll use in this tutorial), Cursor IDE, Claude Desktop etc. This growing ecosystem makes it easier than ever to create AI-powered interfaces for your blockchain data.

Create MCP server for your indexer

Prerequisites

For this tutorial we selected GitHub Copilot for its native VS Code integration, robust MCP support and good selection of supported models.

To follow this guide you will need:

• Python 3
• Visual Studio Code (version 1.99+)
• GitHub Copilot extension

Quickstart

NOTE

If you already have a DipDup indexer project that you want to integrate with MCP, you can skip this section and proceed to the MCP setup part. Make sure that you are running the latest version of DipDup (8.3.2 or later)

Let's quickly set up a DipDup indexer project from scratch:

# 1. Install DipDup
curl -Lsf https://dipdup.io/install.py | python3

# 2. Create a new project using the built-in project generator
dipdup new
# 3. Choose "From template", then "EVM" network and "demo_evm_events" template for this example. This will create an indexer for USDT token transfers on Ethereum.

# 4. Navigate to your project directory and start the indexer:
cd dipdup_indexer

# 5. Make a copy of env file template and fill `NODE_API_KEY` variable (Alchemy in default config)
cp deploy/sqlite.env.default .env

# 6. Start indexer
dipdup -e .env -C sqlite run

Your indexer will start synchronizing with the blockchain and storing token transfer events in the database according to the configuration in dipdup.yaml and configs/dipdup.sqlite.yaml.

MCP Setup

Start DipDup MCP server in a separate terminal:

dipdup -e .env -C sqlite mcp run

Enable agent mode in Github Copilot — modify the .vscode/settings.json file:

{
    "chat.agent.enabled": true
}

Now define MCP server — write to the .vscode/mcp.json:

{
    "servers": {
        "dipdup-sse": {
            "type": "sse",
            "url": "http://127.0.0.1:9999/sse"
        }
    }
}

Open the Chat view and switch to the "Agent" mode. You should see the available tools clicking the 🛠️ icon.

Agent mode

Interacting with server

Let's interact with our assistant, DipDup server exposed numerous tools to Github Copilot, your model is ready to use them now:

Index status

Advanced example

Going further, I want to demonstrate an indexer controlled fully by an AI client via API. Through an LLM, we will add an indexer and query blockchain data using only natural language.

Project description

You can clone my demo from GitHub.

Steps to Create the Project

To build this project, I followed these steps:

1. Created a DipDup project: Started with a blank template to set up the project structure.
2. Configured dipdup.yaml: Added datasources, templates for ERC20 transfer indexers, and other necessary configuration details.
3. Generated contract types: Used DipDup tools to generate types for the ERC20 token contract.
4. Defined data models: Created models in models/__init__.py to store information about transfers and tokens.
5. Implemented handlers: Wrote handlers to process blockchain data and store transfer details in the database.
6. Developed MCP tools: Created mcp/mcp.py to define MCP tools for adding tokens and querying data. Specifically:
   • A tool to add tokens and their corresponding indexers.
   • A tool to query formatted transfer data using the defined models.

How to run

From this project indexer with MCP server could be seamlessly run using either:

Docker Compose with

make up

or locally from cli

dipdup -e .env -C sqlite run

# in another terminal
dipdup -e .env -C sqlite mcp run

In action

Now indexer is waiting without active tasks

Let's ask to index new token

NOTE

MCP Perplexity integration setup is out of scope of this guide, follow the docs to set it up.

Contract and index successfully registered

We are still processing at the start of the indexing

Now let's ask AI about my token transfers

Tool usage

As we see with pre-developed MCP tools very complex scenarios could be realised

Conclusion

These were just examples of how flexible MCP could be; we hope you will find many more.

MCP is a relatively recent technology, so many tools might not work as expected. Consult the Known issues section for more information, and open a ticket in GitHub issues if you encounter any problems.

Explore all the ways to employ DipDup in our docs: DipDup MCP integration page.