Blockchain MCP Standard (BMCPS) v3.0

The Complete Unified Standard for Blockchain MCP Servers

Version: 3.0
Date: January 2025
Author: Myron Koch - AI Director & Protocol Architect
Status: ACTIVE UNIFIED STANDARD
Supersedes: tool requirements (v2.1) and architecture standard (v1.0)

Executive Summary

The Blockchain MCP Standard (BMCPS) v3.0 unifies architecture and tool requirements into a single comprehensive standard for all blockchain MCP servers. This standard ensures consistency, scalability, and production readiness across the entire blockchain MCP ecosystem.

Core Principles
Part 1: Architecture Requirements
Part 2: Tool Requirements
Part 3: Implementation Guide
Part 4: Compliance Verification
Part 5: Reference Implementations

Core Principles

Unified Standard Benefits

Single Source of Truth: One standard for both architecture and functionality
Clear Compliance Path: One checklist covering all requirements
Scalability: Support from 25 to 500+ tools per blockchain
Maintainability: Modular architecture with clear organization
Consistency: Same patterns across all blockchain servers

Key Requirements Summary

Architecture: Modular file structure with standardized categories
Tools: 25 mandatory core tools with specific functionality
Naming: \{prefix\}_\{action\}_\{resource\} convention
Testing: All tools must be functional via MCP Inspector
Documentation: Comprehensive README and inline documentation

Part 1: Architecture Requirements

Mandatory Directory Structure

\{blockchain\}-\{network\}-mcp-server/
├── src/
│   ├── index.ts                 # Main entry point (&lt;300 lines)
│   ├── tool-definitions.ts      # Tool registry and schemas
│   ├── client.ts                # Blockchain client wrapper (optional)
│   ├── constants.ts             # ABIs, addresses, configs (optional)
│   ├── logger.ts                # Logging configuration (optional)
│   ├── types.ts                 # TypeScript definitions (optional)
│   └── tools/                   # Tool implementations (REQUIRED)
│       ├── core/                # Blockchain fundamentals (REQUIRED)
│       ├── wallet/              # Wallet operations (REQUIRED)
│       ├── network/             # Network management (REQUIRED)
│       ├── tokens/              # Token operations (REQUIRED)
│       ├── help/                # Help system (REQUIRED)
│       ├── account/             # Account management
│       ├── nft/                 # NFT operations
│       ├── defi/                # DeFi protocols
│       ├── staking/             # Staking operations
│       ├── governance/          # Governance operations
│       ├── contracts/           # Smart contract operations
│       ├── bridge/              # Cross-chain bridging
│       ├── analytics/           # Analytics and monitoring
│       ├── security/            # Security and audit tools
│       ├── events/              # Event logs and monitoring
│       └── advanced/            # Advanced/specialized tools
├── dist/                        # Compiled output
├── tests/                       # Test suites
│   ├── smoke.test.ts           # Basic functionality
│   ├── integration/            # Integration tests
│   └── unit/                   # Unit tests
├── scripts/                     # Utility scripts
├── docs/                        # Documentation
├── package.json
├── tsconfig.json
├── jest.config.js              # Test configuration
└── README.md

Category Definitions

Required Categories (MUST have)

core/ - Blockchain fundamentals (get_balance, get_transaction, etc.)
wallet/ - Wallet creation and management
network/ - Network information and switching
tokens/ - Token operations and queries
help/ - Help system tools

File Naming Convention

src/tools/\{category\}/\{prefix\}-\{action\}_\{resource\}.ts

Examples:
src/tools/core/xrp-get_balance.ts
src/tools/tokens/xrp-transfer_token.ts
src/tools/nft/xrp-mint_nft.ts

Tool Implementation Template

import \{ z \} from 'zod';
import \{ Client \} from 'xrpl'; // or appropriate client
import \{ McpError, ErrorCode \} from '@modelcontextprotocol/sdk/types.js';

// Input validation schema
const schema = z.object(\{
  address: z.string().describe('Wallet address'),
  // ... other parameters
\});

// Tool handler function
export async function handle\{Action\}\{Resource\}(
  args: any,
  client?: Client // optional client parameter
): Promise<\{ content: Array<\{ type: string; text: string \}> \}> \{
  try \{
    // Validate inputs
    const parsed = schema.parse(args);
    
    // Perform operation
    const result = await performOperation(parsed);
    
    // Return formatted response
    return \{
      content: [\{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      \}]
    \};
  \} catch (error) \{
    if (error instanceof z.ZodError) \{
      throw new McpError(
        ErrorCode.InvalidParams,
        `Invalid parameters: $\{error.errors.map(e => e.message).join(', ')\}`
      );
    \}
    throw new McpError(
      ErrorCode.InternalError,
      `Operation failed: $\{error instanceof Error ? error.message : 'Unknown error'\}`
    );
  \}
\}

Part 2: Tool Requirements

25 Mandatory Core Tools

Every blockchain MCP server MUST implement these exact 25 tools:

Blockchain Operations (5 tools)

\{prefix\}_get_chain_info - Comprehensive blockchain information
\{prefix\}_get_balance - Native token balance for address
\{prefix\}_get_transaction - Transaction details by hash
\{prefix\}_get_block - Block information by number/hash
\{prefix\}_validate_address - Address format validation

Transaction Operations (2 tools)

\{prefix\}_get_transaction_history - Recent transactions for address
\{prefix\}_send_transaction - Send native tokens

Wallet Management (3 tools)

\{prefix\}_create_wallet - Generate new wallet
\{prefix\}_import_wallet - Import from private key/mnemonic
\{prefix\}_generate_address - Generate new address formats

Network Management (3 tools)

\{prefix\}_get_network_info - Network status and config
\{prefix\}_set_network - Switch between networks
\{prefix\}_get_gas_price - Current gas/fee pricing

Fee Management (2 tools)

\{prefix\}_estimate_fees - Fee estimation for transactions
\{prefix\}_get_mempool_info - Mempool statistics

Account Information (2 tools)

\{prefix\}_get_wallet_info - Comprehensive wallet details
\{prefix\}_get_account_info - Account metadata and status

Token Operations (5 tools)

\{prefix\}_get_token_balance - Token balance queries
\{prefix\}_get_token_info - Token metadata
\{prefix\}_transfer_token - Send tokens
\{prefix\}_approve_token - Approve token spending
\{prefix\}_get_token_allowance - Check spending allowances

Help System (3 tools)

\{prefix\}_help - Interactive help and guidance
\{prefix\}_search_tools - Search tools by keyword
\{prefix\}_list_tools_by_category - Browse organized catalog

Tool Naming Convention

\{prefix\}_\{action\}_\{resource\}

Where:
- prefix: Blockchain identifier (eth, btc, sol, xrp, etc.)
- action: Operation verb (get, send, create, validate, etc.)
- resource: Target object (balance, transaction, wallet, etc.)

Examples:
✅ eth_get_balance
✅ btc_create_wallet
✅ sol_send_transaction
❌ getBalance         (wrong format)
❌ ETH_GET_BALANCE    (wrong case)

Extended Tools (Optional)

Servers may implement additional tools based on blockchain capabilities:

DeFi Operations

\{prefix\}_swap_tokens
\{prefix\}_add_liquidity
\{prefix\}_remove_liquidity
\{prefix\}_get_pool_info

NFT Operations

\{prefix\}_mint_nft
\{prefix\}_transfer_nft
\{prefix\}_get_nft_metadata
\{prefix\}_create_nft_collection

Staking Operations

\{prefix\}_stake_tokens
\{prefix\}_unstake_tokens
\{prefix\}_get_staking_rewards
\{prefix\}_get_validators

Cross-Chain Bridge Operations

\{prefix\}_bridge_tokens - Bridge tokens to another chain
\{prefix\}_get_bridge_info - Bridge status and supported chains
\{prefix\}_estimate_bridge_fees - Bridge fee estimation
\{prefix\}_get_bridge_history - Bridge transaction history

Analytics & Monitoring

\{prefix\}_get_analytics - Network and account analytics
\{prefix\}_get_performance_metrics - Performance statistics
\{prefix\}_monitor_transaction - Transaction monitoring
\{prefix\}_get_usage_stats - Usage statistics and patterns

Security & Audit

\{prefix\}_audit_transaction - Transaction security audit
\{prefix\}_validate_security - Security validation checks
\{prefix\}_get_security_status - Security status and alerts
\{prefix\}_check_compliance - Regulatory compliance checks

Events & Logs

\{prefix\}_get_events - Blockchain event logs
\{prefix\}_subscribe_events - Event subscription
\{prefix\}_get_logs - Transaction and contract logs
\{prefix\}_search_logs - Log search and filtering

Part 3: Implementation Guide

Step 1: Initialize Project

# Create project structure
mkdir \{blockchain\}-\{network\}-mcp-server
cd \{blockchain\}-\{network\}-mcp-server
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node jest @types/jest ts-jest

# Create directory structure
mkdir -p src/tools/\{core,wallet,network,tokens,help,account,nft,defi,staking,governance,contracts,bridge,analytics,security,events,advanced\}
mkdir -p tests/\{unit,integration\} scripts docs

Step 2: Configure TypeScript

// tsconfig.json
\{
  "compilerOptions": \{
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true
  \},
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
\}

Step 3: Create Main Index File

// src/index.ts
#!/usr/bin/env node
import \{ Server \} from '@modelcontextprotocol/sdk/server/index.js';
import \{ StdioServerTransport \} from '@modelcontextprotocol/sdk/server/stdio.js';
import \{
  CallToolRequestSchema,
  ListToolsRequestSchema,
  McpError,
  ErrorCode
\} from '@modelcontextprotocol/sdk/types.js';

// Import tool definitions
import \{ TOOL_DEFINITIONS \} from './tool-definitions.js';

// Import tool handlers (organized by category)
// Core tools
import \{ handleGetChainInfo \} from './tools/core/\{prefix\}-get_chain_info.js';
import \{ handleGetBalance \} from './tools/core/\{prefix\}-get_balance.js';
// ... import all 25+ tools

// Initialize server
const server = new Server(
  \{
    name: '\{blockchain\}-\{network\}-mcp-server',
    version: '3.0.0', // Blockchain MCP Standard v3.0 (BMCPS v3.0) compliant
  \},
  \{
    capabilities: \{ tools: \{\} \},
  \}
);

// Register tool definitions
server.setRequestHandler(ListToolsRequestSchema, async () => \{
  return \{ tools: TOOL_DEFINITIONS \};
\});

// Route tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => \{
  const \{ name, arguments: args \} = request.params;
  
  try \{
    switch (name) \{
      // Core tools
      case '\{prefix\}_get_chain_info':
        return await handleGetChainInfo(args);
      case '\{prefix\}_get_balance':
        return await handleGetBalance(args);
      // ... handle all tools
      
      default:
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Unknown tool: $\{name\}`
        );
    \}
  \} catch (error) \{
    if (error instanceof McpError) throw error;
    throw new McpError(
      ErrorCode.InternalError,
      `Tool execution failed: $\{error\}`
    );
  \}
\});

// Start server
async function main() \{
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('[Blockchain MCP Standard v3.0 (BMCPS v3.0)] \{Blockchain\} MCP Server running');
  console.error(`[Blockchain MCP Standard v3.0 (BMCPS v3.0)] Total tools: $\{TOOL_DEFINITIONS.length\}`);
\}

main().catch(console.error);

Step 4: Implement Core Tools

Start with the 25 mandatory tools, one file per tool:

// src/tools/core/\{prefix\}-get_balance.ts
import \{ z \} from 'zod';

const schema = z.object(\{
  address: z.string().describe('Wallet address to check balance')
\});

export async function handleGetBalance(args: any) \{
  const \{ address \} = schema.parse(args);
  
  // Implementation here
  const balance = await fetchBalance(address);
  
  return \{
    content: [\{
      type: 'text',
      text: JSON.stringify(\{
        address,
        balance: balance.formatted,
        balanceRaw: balance.raw,
        symbol: 'ETH' // or appropriate symbol
      \}, null, 2)
    \}]
  \};
\}

Part 4: Compliance Verification

Blockchain MCP Standard v3.0 (BMCPS v3.0) Compliance Checklist

Architecture Requirements ✓

Project follows mandatory directory structure
Tools organized in category folders
One tool per file pattern
Index.ts under 300 lines
Tool definitions in separate file

Tool Requirements ✓

All 25 mandatory core tools implemented
Tool naming follows \{prefix\}_\{action\}_\{resource\}
All tools have proper input schemas
Help system fully functional
Network switching capability

Code Quality ✓

TypeScript compiles without errors
Zod validation on all inputs
Comprehensive error handling
Consistent response format
No private keys in code

Testing Requirements ✓

Compliance Levels

🥉 Blockchain MCP Standard v3.0 (BMCPS v3.0) Bronze

✅ 25 core tools implemented
✅ Basic modular structure
✅ TypeScript compilation works

🥈 Blockchain MCP Standard v3.0 (BMCPS v3.0) Silver

✅ All Bronze requirements
✅ Full BMCPS v3.0 architecture compliance
✅ Extended tools (40+ total)
✅ Comprehensive testing suite
✅ Documentation complete

🥇 Blockchain MCP Standard v3.0 (BMCPS v3.0) Gold

✅ All Silver requirements
✅ 100+ tools organized
✅ Performance optimized
✅ Security audited
✅ Production deployed

Verification Commands

# Check compilation
npm run build

# Test all tools
npm run test

# Verify with MCP Inspector
npm run inspect

# Check compliance
npm run mbss-check  # Custom script to verify standards

Part 5: Reference Implementations

Gold Standard Examples

Production Ready (Gold)

Osmosis Mainnet: 119 tools, full modular architecture
XRP Testnet: 40 tools, clean BMCPS v3.0 structure

Silver Standard

Polygon Testnet: 29 tools, BMCPS v3.0 compliant
Avalanche Testnet: 25 tools, reference architecture

Migration Examples

From Monolithic (Before)

// Everything in one massive index.ts file
switch (toolName) \{
  case 'get_balance': // 3000+ lines of cases
    // implementation inline
  case 'send_transaction':
    // implementation inline
  // ... 100+ more cases
\}

To Modular Blockchain MCP Standard v3.0 (BMCPS v3.0) (After)

// Clean index.ts with imports
import \{ handleGetBalance \} from './tools/core/eth-get_balance.js';

switch (toolName) \{
  case 'eth_get_balance':
    return await handleGetBalance(args);
  // ... clean routing only
\}

Appendix A: Chain Prefix Registry

Blockchain	Prefix	Example Tool
Ethereum	`eth_`	eth_get_balance
Bitcoin	`btc_`	btc_get_transaction
Solana	`sol_`	sol_create_wallet
Polygon	`poly_`	poly_get_gas_price
Avalanche	`avax_`	avax_get_validators
Arbitrum	`arb_`	arb_estimate_fees
Base	`base_`	base_get_network_info
BNB Chain	`bnb_`	bnb_swap_tokens
XRP	`xrp_`	xrp_get_escrows
NEAR	`near_`	near_get_staking_info
Sui	`sui_`	sui_get_objects
TRON	`tron_`	tron_get_energy
Cosmos	`cosmos_`	cosmos_get_proposals
Osmosis	`osmo_`	osmo_get_pools
World Chain	`world_`	world_verify_world_id

Appendix B: Tool Categories Quick Reference

Always Required

core/ - Blockchain fundamentals
wallet/ - Wallet management
network/ - Network operations
tokens/ - Token operations
help/ - Help system

Common Extensions

account/ - Extended account features
nft/ - NFT operations
defi/ - DeFi protocols
staking/ - Staking operations
contracts/ - Smart contract interactions
bridge/ - Cross-chain bridging operations
analytics/ - Analytics and monitoring tools
security/ - Security and audit operations
events/ - Event logs and monitoring

Chain-Specific

governance/ - DAO/governance (Cosmos, etc.)
validators/ - Validator info (PoS chains)
programs/ - Programs (Solana)
inscriptions/ - Inscriptions (Bitcoin)
ibc/ - IBC operations (Cosmos)

Appendix C: Migration Timeline

Immediate (Now)

All new servers must follow Blockchain MCP Standard v3.0 (BMCPS v3.0)
Existing servers should plan migration

Q1 2025

All testnet servers Blockchain MCP Standard v3.0 (BMCPS v3.0) compliant
Migration scripts available

Q2 2025

All mainnet servers Blockchain MCP Standard v3.0 (BMCPS v3.0) compliant
Deprecate tool requirements (v2.1) and architecture standard (v1.0)

Q3 2025

BMCPS v3.1 with advanced features
Cross-chain standards

Version History

v3.0 (Jan 2025): Unified tool requirements (v2.1) + architecture standard (v1.0)
v2.1 (Dec 2024): MBPS tool requirements
v1.0 (Sep 2024): MSAS architecture standard

This unified standard supersedes all previous standards.

One Standard. Complete Compliance. Production Ready.

Maintained at: /servers/testnet/NEW STANDARDS/Blockchain-MCP-Standard-v3.0-UNIFIED-STANDARD.md

The Complete Unified Standard for Blockchain MCP Servers​

Executive Summary​

Table of Contents​

Core Principles​

Unified Standard Benefits​

Key Requirements Summary​

Part 1: Architecture Requirements​

Mandatory Directory Structure​

Category Definitions​

Required Categories (MUST have)​

Optional Categories (as needed)​

File Naming Convention​

Tool Implementation Template​

Part 2: Tool Requirements​

25 Mandatory Core Tools​

Blockchain Operations (5 tools)​

Transaction Operations (2 tools)​

Wallet Management (3 tools)​

Network Management (3 tools)​

Fee Management (2 tools)​

Account Information (2 tools)​

Token Operations (5 tools)​

Help System (3 tools)​

Tool Naming Convention​

Extended Tools (Optional)​

DeFi Operations​

NFT Operations​

Staking Operations​

Cross-Chain Bridge Operations​

Analytics & Monitoring​

Security & Audit​

Events & Logs​

Part 3: Implementation Guide​

Step 1: Initialize Project​

Step 2: Configure TypeScript​

Step 3: Create Main Index File​

Step 4: Implement Core Tools​

Part 4: Compliance Verification​

Blockchain MCP Standard v3.0 (BMCPS v3.0) Compliance Checklist​

Architecture Requirements ✓​

Tool Requirements ✓​

Code Quality ✓​

Testing Requirements ✓​

Compliance Levels​

🥉 Blockchain MCP Standard v3.0 (BMCPS v3.0) Bronze​

🥈 Blockchain MCP Standard v3.0 (BMCPS v3.0) Silver​

🥇 Blockchain MCP Standard v3.0 (BMCPS v3.0) Gold​

Verification Commands​

Part 5: Reference Implementations​

Gold Standard Examples​

Production Ready (Gold)​

Silver Standard​

Migration Examples​

From Monolithic (Before)​

To Modular Blockchain MCP Standard v3.0 (BMCPS v3.0) (After)​

Appendix A: Chain Prefix Registry​

Appendix B: Tool Categories Quick Reference​

Always Required​

Common Extensions​

Chain-Specific​

Appendix C: Migration Timeline​

Immediate (Now)​

Q1 2025​

Q2 2025​

Q3 2025​

Version History​