back to posts
#10 • Part 2 • 2025-08-12 • 25 min

The MBPS v2.1 Standard: How Chaos Became Order

Building a universal standard for 17 blockchain MCP servers that actually works

MBPS v2.1 standards naming lessons learned

Part 2 of the Journey: Discovering the Patterns - Learning Through Pain Previous: The Cross-Chain Tool Naming Registry | Next: From Manual to Meta: The Complete MCP Factory Story

The MBPS v2.1 Standard: How Chaos Became Order

Building a universal standard for 17 blockchain MCP servers that actually works

Historical Context (November 2025): Created August 2025 after building 17 servers manually revealed the need for standardization. MBPS v2.1 emerged from real production patterns, not theoretical design—experience-driven standards that later enabled the MCP Factory automation.

Date: August 12, 2025 Author: Myron Koch & Claude Code Category: Standards & Architecture

The Chaos Era

December 2024. We had 17 blockchain MCP servers. Each one unique. Each one special. Each one a nightmare.

ethereum-mcp-server/
├── index.js (5,847 lines)
├── package.json
└── README.md (3 lines: "Ethereum MCP Server")

solana-mcp-server/
├── src/
│   ├── main.ts (3,200 lines)
│   ├── utils.ts
│   └── types.ts
└── [no tests]

bitcoin-mcp-server/
├── server.js (4,100 lines)
├── bitcoin-stuff.js
└── [console.log everywhere]

No patterns. No standards. No sanity.

The Breaking Point

January 15, 2025. We tried to add a simple feature across all servers:

“Add get_gas_price to all EVM chains”

Time estimate: 2 hours Actual time: 3 days

Why? Every server was different:

The Birth of MBPS v2.1

Model Context Protocol Blockchain Production Standard

Version 2.1 because:

The Core Principles

1. Mandatory Structure

Every server MUST have this exact structure:

{blockchain}-{network}-mcp-server/
├── src/
│   ├── index.ts              # <300 lines, always
│   ├── client.ts             # Blockchain client only
│   ├── config/
│   │   └── network.ts        # Network configurations
│   ├── tools/                # Modular tools
│   │   ├── core/            # Required tools
│   │   ├── wallet/          # Wallet operations
│   │   ├── tokens/          # Token operations
│   │   └── [category]/      # Domain-specific
│   ├── types/
│   └── utils/
├── tests/
│   ├── smoke.test.ts         # Server starts?
│   ├── integration.test.ts  # Tools registered?
│   └── core.test.ts         # Tools work?
└── package.json

No exceptions. No creativity. Follow the structure.

2. The 25 Mandatory Tools

Every blockchain, no matter how different, must implement:

// Core Operations (5)
{prefix}_get_chain_info
{prefix}_get_balance
{prefix}_get_transaction
{prefix}_get_block
{prefix}_validate_address

// Wallet Management (5)
{prefix}_create_wallet
{prefix}_import_wallet
{prefix}_generate_address
{prefix}_get_wallet_info
{prefix}_send_transaction

// Token Operations (5)
{prefix}_get_token_balance
{prefix}_get_token_info
{prefix}_transfer_token
{prefix}_approve_token
{prefix}_get_token_allowance

// Smart Contracts (5)
{prefix}_deploy_contract
{prefix}_call_contract
{prefix}_get_contract_info
{prefix}_get_logs
{prefix}_estimate_gas

// Help System (5)
{prefix}_help
{prefix}_search_tools
{prefix}_list_tools_by_category
{prefix}_get_network_info
{prefix}_set_network

3. Tool File Naming

One tool, one file, specific naming:

src/tools/core/eth-get-balance.ts       ✅
src/tools/core/getBalance.ts            ❌
src/tools/eth_get_balance.ts            ❌
src/tools/core/ethereum-balance.ts      ❌

Pattern: {prefix}-{action}-{resource}.ts

4. Tool Implementation Pattern

Every tool follows this exact pattern:

// src/tools/core/eth-get-balance.ts
import { BlockchainClient } from '../../client.js';

export async function handleEthGetBalance(
  args: any,
  client: BlockchainClient
): Promise<{
  content: Array<{
    type: string;
    text: string;
  }>;
}> {
  // Validate input
  if (!args.address) {
    throw new Error('Address required');
  }

  // Execute operation
  const balance = await client.getBalance(args.address);

  // Return MCP format
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        address: args.address,
        balance: balance.toString(),
        unit: 'ETH'
      }, null, 2)
    }]
  };
}

The Enforcement Mechanism

We built scripts to enforce MBPS v2.1:

// scripts/validate-mbps.js
function validateServer(serverPath) {
  const violations = [];

  // Check structure
  if (!fs.existsSync(`${serverPath}/src/tools/core`)) {
    violations.push('Missing src/tools/core directory');
  }

  // Check mandatory tools
  MANDATORY_TOOLS.forEach(tool => {
    if (!findToolImplementation(serverPath, tool)) {
      violations.push(`Missing mandatory tool: ${tool}`);
    }
  });

  // Check index.ts size
  const indexSize = getLineCount(`${serverPath}/src/index.ts`);
  if (indexSize > 300) {
    violations.push(`index.ts too large: ${indexSize} lines (max: 300)`);
  }

  return violations;
}

The Migration Pain

Migrating 17 servers to MBPS v2.1 was brutal:

Week 1: Extraction

// Extract tools from monolithic files
node scripts/extract-tools.js ethereum-mcp-server
// Created 47 individual tool files from 5,847-line index.js

Week 2: Standardization

// Rename tools to match standard
node scripts/standardize-tool-names.js
// Renamed 623 tools across 17 servers

Week 3: Testing

// Add mandatory test suites
node scripts/generate-tests.js
// Created 51 test files

Week 4: Validation

./scripts/validate-all-servers.sh
# 17 servers validated
# 0 violations
# MBPS v2.1 compliant ✅

The Unexpected Benefits

1. New Server in 30 Minutes

./scripts/create-new-blockchain-mcp.sh avalanche testnet
# Generates complete MBPS v2.1 compliant server
# Just add blockchain-specific client code

2. Cross-Training Possible

Developer knows Ethereum MCP server? They now know:

Same structure everywhere.

3. Bulk Operations

// Add new tool to all servers
servers.forEach(server => {
  copyFile('templates/get-gas-price.ts',
          `${server}/src/tools/core/${prefix}-get-gas-price.ts`);
});
// 17 servers updated in 30 seconds

4. AI Navigation

User: "Add NFT minting to Polygon"
AI: *knows exactly where to put it*
→ servers/polygon-mcp-server/src/tools/nft/

The Resistance

Not everyone loved MBPS v2.1:

“It’s too rigid!” Yes. That’s the point.

“But Solana doesn’t have gas!” Implement get_gas_price anyway. Return appropriate message.

“Bitcoin doesn’t have smart contracts!” Implement the tools. Document limitations.

“This feels like bureaucracy!” It is. Good bureaucracy that makes 17 servers manageable.

Real-World Impact

Before MBPS v2.1:

After MBPS v2.1:

The Living Standard

MBPS v2.1 evolves:

## Changelog

### v2.1.1 (Feb 2025)
- Added `get_transaction_history` to mandatory tools
- Clarified BigInt handling in responses

### v2.1.2 (Mar 2025)
- Added DeFi category with 4 mandatory tools
- Updated test requirements for async operations

### v2.1.3 (Apr 2025)
- Added NFT category for chains with NFT support
- Standardized error response format

The Compliance Dashboard

We track compliance:

MBPS v2.1 Compliance Status (October 2025)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Osmosis       100% (158/158 tools)
✅ BSC Testnet   100% (36/36 tools)
✅ World Chain   100% (71/71 tools)
✅ XRP Testnet   100% (44/44 tools)
✅ Avalanche     100% (40/40 tools)
⚠️  Ethereum      92% (46/50 tools) - 4 missing
⚠️  Solana        87% (44/50 tools) - 6 missing
❌ Bitcoin       72% (36/50 tools) - 14 missing

The Document That Rules Them All

/servers/testnet/NEW STANDARDS/01-MBPS-v2.1-COMPREHENSIVE.md

38 pages. Every detail. Every rule. Every pattern.

Teams print it. Frame it. Follow it.

The Lesson

Standards are constraints that create freedom.

Without MBPS v2.1:

With MBPS v2.1:

The Future: MBPS v3.0

Coming 2026:

But v2.1 works. Today. For 17 blockchains.

And that’s the real achievement.

References

This is part of our ongoing series documenting architectural patterns and insights from building the Blockchain MCP Server Ecosystem. Standards aren’t sexy, but they’re essential.

Prerequisites

Next Steps

Deep Dives