MCP server for Substrate-based chains

[jakehemmerle]

Project Abstract

mcp-polkadot aims to expose any Substrate-based chain's on-chain state to AI agents via the Model-Context Protocol (MCP). More examples of MCP can be found here

Grant level

• Level 1: Up to $10,000, 2 approvals
• Level 2: Up to $30,000, 3 approvals
• Level 3: Unlimited, 5 approvals (for >$100k: Web3 Foundation Council approval)

Application Checklist

• The application template has been copied and aptly renamed (project_name.md).
• I have read the application guidelines.
• Payment details have been provided (Polkadot AssetHub (USDC & DOT) address in the application and bank details via email, if applicable).
• I understand that an agreed upon percentage of each milestone will be paid in vested DOT, to the Polkadot address listed in the application.
• I am aware that, in order to receive a grant, I (and the entity I represent) have to successfully complete a KYC/KYB check.
• The software delivered for this grant will be released under an open-source license specified in the application.
• The initial PR contains only one commit (squash and force-push if needed).
• The grant will only be announced once the first milestone has been accepted (see the announcement guidelines).
• I prefer the discussion of this application to take place in a private Element/Matrix channel. My username is: @_______:matrix.org (change the homeserver if you use a different one)

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[jakehemmerle]

I have read and hereby sign the Contributor License Agreement.

[keeganquigley]

Hi @jakehemmerle nice to talk to you again. I see you marked 0% for DOT payment, however at least 50% DOT (vested linearly over two years) is mandatory now for the grants program. Would you be willing to accept half the payment in DOT and if so could you update this?

[jakehemmerle]

Hi @jakehemmerle nice to talk to you again. I see you marked 0% for DOT payment, however at least 50% DOT (vested linearly over two years) is mandatory now for the grants program. Would you be willing to accept half the payment in DOT and if so could you update this?

Hey Kegan! I hope all is well in your world. Just updated it.

Another thing, I now realize that grants for individual contributors might aim for a max $10k grant instead of max $30k. Would it be better to decompose this into a smaller set of milestones and aim for the $10k instead?

[keeganquigley]

Thanks @jakehemmerle much appreciated. I have marked the application as ready for review and will ping the rest of the committee for comment.

To answer your question, I would leave as is for now and you can always change it down the line if it isn't accepted. Thanks!

[KarimJedda]

A small suggestion from me would be to not call it mcp-substrate but rather mcp-polkadot. Would that work?

[jakehemmerle]

A small suggestion from me would be to not call it mcp-substrate but rather mcp-polkadot. Would that work?

Is there a reason, semantically, that mcp-polkadot is more descriptive? This would work for any Substrate-based runtime (eg. Polkadot, Astar, Entropy, etc).

[KarimJedda]

Developer tooling & resources will benefit from consolidation around the Polkadot brand, given the branding overhaul initiated across the ecosystem in the past months/year.

These two non-exhaustive links might provide a bit more context:

• https://forum.polkadot.network/t/one-repo-to-rule-them-all-a-data-driven-look-at-polkadot-s-monorepo/5976
• https://forum.polkadot.network/t/polkadot-developers/9788

Ideally you want to reduce possible confusion and reduce cognitive load on people that don't have the full history in mind.

In short, it's all Polkadot.

[jakehemmerle]

@KarimJedda Right on, thanks for the context. Happy to change to mcp-polkadot.

[jakehemmerle]

@keeganquigley can you let me know what is missing from the review? If payment details are the bottleneck, can you let me know what email to send them to?

[keeganquigley]

Thanks @jakehemmerle yes can you please send them to [email protected]

Much of the team is ooo this week, sorry for the delay.

[jakehemmerle]

Good morning @keeganquigley , anything I help with on my end for this?

[keeganquigley]

Sorry for the delay here, just a couple more clarifying technical questions:

• Could you elaborate on how specific Substrate runtime metadata components (storage maps, constants, pallets) will be translated into MCP "resources"? Will there a be a default mapping, and how customizable will it be?
• What are the anticipated challenges in dynamically generating these resources given the potential diversity and complexity of Substrate runtimes?
• How will the server handle errors from Polkadot.js and present them to the MCP client?
• How will it handle runtime metadata updates?
• Do you know of any other blockchain networks that are utilizing MCP?

Thanks for any further insights you can provide.

[jakehemmerle]

Could you elaborate on how specific Substrate runtime metadata components (storage maps, constants, pallets) will be translated into MCP "resources"? Will there a be a default mapping, and how customizable will it be?

For simply serving on-chain state (as Resources), the MCP server can wrap around Polkadot.js and get all queryable pallet data from its query interface. From those JS key-value pairs, the server dynamically generates the schema the LLM needs to 'fill out'.

What are the anticipated challenges in dynamically generating these resources given the potential diversity and complexity of Substrate runtimes?

Using or looking to PolkadotJS and subxt for techniques is the obvious solution. It's SCALE-encoded schema. I wrote Substrate runtimes for Entropy for almost 2 years so I feel like I have a pretty good feel of what issues I might run into.

How will the server handle errors from Polkadot.js and present them to the MCP client?

Standard error handling seems appropriate, where the server would just format PolkadotJS errors as text and return to the client.

How will it handle runtime metadata updates?

The MCP server is relatively stateless, so restarting the daemon or having it reload on runtime update Events would be easy. The server would be able to be started with a single argument (the URL to a Substrate RPC endpoint), which fetches the metadata runtime at startup and then generates the resources.

Do you know of any other blockchain networks that are utilizing MCP?

Networks themselves wouldn't really utilize MCP, it would be a service that (non-validating) node operators host (the same way projects host associated services like a frontend for their web3 apps).

One example for EVM-compatible endpoints is here: https://github.com/Phillip-Kemper/ethereum-rpc-mpc
Another for Bitcoin: https://github.com/AbdelStark/bitcoin-mcp

[semuelle]

Hi @jakehemmerle, thanks for the application. I am happy to support it. The only question I have is whether you actually plan on working on the items listed in the Future Plans section, or what the deciding factor would be.

[keeganquigley]

Sorry for the delay @jakehemmerle and thanks for your thorough answers. I'm happy to approve as well.

[keeganquigley]

While waiting for further reviews could you please also complete KYB verification for the legal entity, or KYC in the case that it is just yourself? This is now required for all applicants. Thanks!

[jakehemmerle]

Thanks for the support @semuelle @keeganquigley

@semuelle :

The only question I have is whether you actually plan on working on the items listed in the Future Plans section, or what the deciding factor would be.

Biggest on my end would probably be grant support and feature prioritization. Obviously, the hope with grants is that the output is integrated into the ecosystem in some capacity. It'd be important to prioritize the Future Plan items, so we would probably want to talk with teams that are already using AI heavily in their product, documentation, or engineering workflows (maybe client fuzzing in CI?) sooner rather than later to gauge integration and get feedback. Any teams you can think of to connect with first?

A first use case for this MVP version could be an AI-powered chat assistant that is hosted on indexer sites. Imagine Etherscan-equivalent had a click-window in the bottom right and I could say "What contract did XYZ address most recently interact with". That would also give us info on what users are intending to do, to help feature prioritization. Maybe getting in touch with teams providing index services or node/service providers could be a great start on that front.