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.

[PieWol]

Hey @jakehemmerle ,
thanks for the application. I'm happy to support it!
Most grantees prefer medium for publishing an article.

[semuelle]

Thanks for the info, @jakehemmerle. We are only missing KYC now, then we're ready to merge.

[github-actions]

Congratulations and welcome to the Web3 Foundation Grants Program! Please refer to our Milestone Delivery repository for instructions on how to submit milestones and invoices, our FAQ for frequently asked questions and the support section on our website for more ways to find answers to your questions.

Before you start, take a moment to read through our announcement guidelines for all communications related to the grant or make them known to the right person in your organisation. In particular, please don't announce the grant publicly before at least the first milestone of your project has been approved. At that point or shortly before, you can get in touch with us at [email protected] and we'll be happy to collaborate on an announcement about the work you’re doing.

Also, if you haven't yet, consider signing up for the Polkadot Alpha Program. The program offers plenty of resources for people building on Polkadot. Lastly, please remember to let us know in case you run into any delays or deviate from the deliverables in your application. You can either leave a comment here or directly request to amend your application via PR. We wish you luck with your project! 🚀

[KarimJedda]

Hi all, where can I follow the progress of this initiative? :)

[semuelle]

Question for @jakehemmerle. We haven't received any deliveries or status updates yet.

[jakehemmerle]

Sorry for the silence @KarimJedda @semuelle , I've been wrapping up a project that is taking longer than I expected. Can I check back in two weeks?

[jakehemmerle]

I just rereviewed the Grant criteria and I see the clause about maintaining an updated timelines. Can we plan for a late august completion?

[semuelle]

No rush from my side, @jakehemmerle . We are not super strict with timelines. I think Karim is just interested in your project.

[jakehemmerle]

Right on! Will keep you all updated :)

[keeganquigley]

Hi @jakehemmerle since you aren't able to work on this currently, I think we should go ahead and cancel since we have another team working on it. We can potentially open it again later on should you wish to continue working on it. Let me know if this sounds good; will plan to close it in a few days.

[jakehemmerle]

Hey @keeganquigley sorry again for the lack of communication. I'm stoked to hear you've got another team working on this. If it makes sense financially to cancel this and let them finish, I totally understand, otherwise I will start on this in the next day or two. Let me know what you'd prefer. No hard feeling.