DEV Community

xyaz1313
xyaz1313

Posted on

Using midnight-mcp for Contract Development with AI Assistants

#ai #blockchain #mcp #tooling

Using midnight-mcp for Contract Development with AI Assistants

I've been exploring how to make Midnight smart contract development faster, and stumbled upon midnight-mcp — a Model Context Protocol server that connects AI assistants directly to the Midnight blockchain. After setting it up with Claude Desktop, I found it genuinely useful for catching bugs early and understanding the Compact language faster. Here's how to get started.

What is midnight-mcp?

midnight-mcp is an MCP (Model Context Protocol) server that gives AI assistants like Claude, Cursor, and VS Code Copilot direct access to Midnight blockchain capabilities. It includes 29 tools covering:

  • Search — Find Compact code, TypeScript patterns, and documentation
  • Analysis — Analyze contracts, explain circuits, compile code
  • Code Generation — Generate, review, and document contracts
  • Versioning — Track breaking changes and migration guides

The best part? No API keys needed. Just install and go.

Prerequisites

  • Node.js 20+ (check with node --version)
  • One of: Claude Desktop, Cursor, VS Code with Copilot, or Windsurf

Step 1: Installation

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "midnight": {
      "command": "npx",
      "args": ["-y", "midnight-mcp@latest"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Using nvm? Claude Desktop might not see your nvm-managed Node. Use this config instead:

{
  "mcpServers": {
    "midnight": {
      "command": "/bin/sh",
      "args": [
        "-c",
        "source ~/.nvm/nvm.sh && nvm use 20 >/dev/null 2>&1 && npx -y midnight-mcp@latest"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "midnight": {
      "command": "npx",
      "args": ["-y", "midnight-mcp@latest"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

VS Code Copilot

Use Command Palette: MCP: Add Server → "command (stdio)" → npx -y midnight-mcp@latest

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "midnight": {
      "command": "npx",
      "args": ["-y", "midnight-mcp@latest"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Restart your editor after adding the config.

Tip: Use @latest to get updates on each restart. If upgrading, clear your npx cache: rm -rf ~/.npm/_npx

Step 2: Verify Installation

After restarting your editor, check if midnight-mcp is working:

  1. Open Claude Desktop (or your chosen editor)
  2. Ask: "Check midnight-mcp status"
  3. You should see a response confirming the server is running

If it's not working, check:

  • Node.js version is 20+
  • Config file is in the correct location
  • Editor was restarted after config changes

Step 3: Exploring the Tools

Here's what I found most useful during development:

Searching Documentation

Instead of hunting through docs manually, just ask:

"Search midnight docs for how to handle private state"
Enter fullscreen mode Exit fullscreen mode

The midnight-search-docs tool finds relevant documentation sections and returns them with context.

Analyzing Contracts

When you have a Compact contract, you can analyze it:

"Analyze this contract for security issues"
Enter fullscreen mode Exit fullscreen mode

The midnight-analyze-contract tool checks for common patterns and potential issues.

Real Compilation

This is the killer feature. The midnight-compile-contract tool actually compiles your Compact code against the Midnight compilation endpoint:

"Compile this contract and tell me if there are errors"
Enter fullscreen mode Exit fullscreen mode

It's not just syntax checking — it's real compilation that catches type errors, missing imports, and logic issues.

Code Generation

Need a starting point? Ask the AI to generate a contract:

"Generate a simple token contract with transfer functionality"
Enter fullscreen mode Exit fullscreen mode

The midnight-generate-contract tool creates boilerplate code you can build on.

Step 4: Real-World Usage

Here's a development session I had with midnight-mcp:

Scenario: Building a Privacy-Preserving Allowlist

I wanted to build a contract where an admin adds members to an allowlist, and members can prove membership without revealing their identity.

Step 1: Ask for help

"How do I build a Merkle tree-based allowlist in Compact?"
Enter fullscreen mode Exit fullscreen mode

Claude used midnight-search-docs and midnight-search-compact to find relevant examples.

Step 2: Generate starter code

"Generate a basic allowlist contract with Merkle tree verification"
Enter fullscreen mode Exit fullscreen mode

The AI generated a working contract skeleton using midnight-generate-contract.

Step 3: Review and fix

"Review this contract for security issues"
Enter fullscreen mode Exit fullscreen mode

midnight-review-contract caught a missing nullifier check that could allow replay attacks.

Step 4: Compile and test

"Compile this contract and fix any errors"
Enter fullscreen mode Exit fullscreen mode

The real compilation endpoint found a type mismatch I would have missed.

What I Learned

  1. Start with questions, not code. Let the AI search docs first — it finds patterns you might miss.

  2. Use the compound tools. midnight-upgrade-check and midnight-get-repo-context save 50-70% of tokens by combining multiple operations.

  3. Verify AI output. Always compile generated code. The AI can make mistakes, but the compiler catches them.

  4. Use versioning tools. When Midnight updates, midnight-check-breaking-changes tells you exactly what changed.

Step 5: Advanced Tips

Tool Categories

The 29 tools are organized into categories. You can explore them:

"List all midnight-mcp tool categories"
"Show me tools in the Analysis category"
Enter fullscreen mode Exit fullscreen mode

Token Efficiency

The compound tools are designed to save tokens:

  • midnight-upgrade-check: Combines version check + breaking changes + migration guide
  • midnight-get-repo-context: Fetches relevant repo structure in one call

Use these instead of multiple individual tool calls.

Custom Workflows

You can chain tools for complex tasks:

"Search for Compact examples, then analyze the best one, then explain how to adapt it for my use case"
Enter fullscreen mode Exit fullscreen mode

The AI will use multiple tools in sequence to give a comprehensive answer.

Troubleshooting

"Server not found" error

  • Check Node.js version: node --version (needs 20+)
  • Verify config file location and syntax
  • Restart your editor completely

Tools not responding

  • Check internet connection (tools fetch live data)
  • Try @latest to ensure you have the newest version
  • Clear npx cache: rm -rf ~/.npm/_npx

Compilation errors

  • Make sure your Compact code syntax is valid
  • Check Midnight docs for current syntax (it's evolving)
  • Use midnight-get-latest-syntax to check for updates

Resources

This tutorial was written for the Midnight Contributor Hub bounty program. #MidnightforDevs

Found this helpful? Star the midnight-mcp repo and join the Midnight Discord to connect with other developers.

Deep Dive: How the Tools Work

Understanding what's happening under the hood helps you use the tools more effectively.

Search Tools

The search tools use semantic search, not just keyword matching. When you ask "how to handle private state", it understands concepts like "confidentiality", "ZK proofs", and "shielded transactions".

Available search tools:

  • midnight-search-compact: Search Compact language examples
  • midnight-search-typescript: Search TypeScript witness implementations
  • midnight-search-docs: Search official documentation
  • midnight-fetch-docs: Fetch specific documentation pages

Analysis Tools

The analysis tools combine static analysis with the Midnight compiler:

  • midnight-analyze-contract: Checks for common security patterns
  • midnight-explain-circuit: Breaks down ZK circuit structure
  • midnight-extract-contract-structure: Shows contract interface
  • midnight-compile-contract: Real compilation against Midnight endpoint

Versioning Tools

Midnight is actively evolving. These tools help you stay current:

  • midnight-get-version-info: Check current SDK version
  • midnight-check-breaking-changes: Find what changed between versions
  • midnight-get-migration-guide: Get upgrade instructions
  • midnight-compare-syntax: Compare old vs new syntax

AI Generation Tools

These require sampling mode to be enabled:

  • midnight-generate-contract: Generate contract code
  • midnight-review-contract: Review for security issues
  • midnight-document-contract: Generate documentation

Setting Up a Development Environment

For the best experience, I recommend this setup:

1. Create a project structure 

my-midnight-project/
├── contracts/          # Compact contracts
├── witnesses/          # TypeScript witnesses
├── tests/              # Test files
└── .cursor/            # Cursor config
    └── mcp.json        # midnight-mcp config
Enter fullscreen mode Exit fullscreen mode

2. Initialize with hello world

Start with the official hello world example from Midnight docs, then iterate using midnight-mcp tools.

3. Use the AI as a pair programmer

Don't just ask for code. Ask questions like:

  • "What's the best pattern for handling X in Compact?"
  • "Review my approach before I implement it"
  • "What are the security considerations for this design?"

This leads to better code than just generating and fixing.

Common Patterns I've Discovered

Using midnight-mcp regularly, I've found these patterns work well:

Pattern 1: Question → Search → Generate → Compile

  1. Ask a conceptual question
  2. Let AI search docs for examples
  3. Generate code based on findings
  4. Compile to verify

Pattern 2: Write → Review → Fix

  1. Write your contract manually
  2. Ask AI to review for issues
  3. Fix based on feedback
  4. Compile to verify

Pattern 3: Migrate → Compare → Update

  1. Check for breaking changes
  2. Compare old vs new syntax
  3. Update code accordingly
  4. Compile to verify

Performance Notes

  • First run is slow. The first compilation downloads ~30MB of ZK parameters. Subsequent runs are faster.
  • Use compound tools. They save 50-70% tokens compared to individual tool calls.
  • Cache is your friend. Once you've searched for something, the AI remembers the context.

Final Thoughts

midnight-mcp made Midnight development significantly more accessible for me. The ability to ask natural language questions and get accurate, contextual answers about Compact syntax and patterns is invaluable.

The real compilation feature alone is worth the setup — catching errors before deployment saves hours of debugging.

If you're building on Midnight, give it a try. Start with Claude Desktop since it has the best MCP support, then expand to your preferred editor.

Last updated: April 13, 2026

Top comments (0)