MCP

A simplified MCP (Model Context Protocol) adapter for the Execution Escrow system that provides a single tool for requesting transaction verification, plus utilities for key generation.

Looking for a complete example? See the Claude Agent Quickstart for a fully functional agent using this MCP adapter with blockchain tools.

Overview

This adapter exposes the requestVerification method from ExecutionEscrowCore as an MCP tool, allowing AI models to request verification for blockchain transactions through the Execution Escrow system. It also includes a command-line tool for generating the required PGP and P-256 cryptographic keys.

Installation

npm install @navalabs/execution-escrow-adapter
# or
pnpm add @navalabs/execution-escrow-adapter

Quick Setup

Step 1: Generate Keys and Configuration

First, generate your cryptographic keys and MCP configuration file:

pnpm generate-escrow-keys privy mypassphrase

Note: If you're using npm, you can run:

npx generate-escrow-keys privy mypassphrase

This command will:

• Generate PGP and P-256 cryptographic keys
• Display keys in the terminal for security (no files written)
• Create a complete mcp-config.json file with your generated keys
• Show wallet-specific configuration instructions

Fireblocks Integration: We support Fireblocks wallet integration. Please contact us to set up Fireblocks for your deployment.

Step 2: Complete Configuration

After running the key generation command, you'll have a mcp-config.json file with placeholder values that need to be replaced. Open the RegisterAgentModal in your browser and follow these steps:

1. Determine Desired Execution Type

   • EXECUTION_TYPE = 1 (Recommended) - Arbiter verifies your transaction, then you sign and execute it
   • EXECUTION_TYPE = 2 - Arbiter verifies and executes the transaction on your behalf
   • EXECUTION_TYPE = 0 - Direct execution, no arbiter review

2. Get API Key (Step 1): Copy the NAVA_API_KEY value and replace "your-nava-api-key-from-register-agent-modal" in your config

3. Register PGP Key (Step 2):

   • Copy your generated PGP public key from the terminal output
   • Paste it into the RegisterAgentModal PGP registration step
   • Copy the PGP_ARBITER_PUBLIC_KEY and replace "pgp-arbiter-key-from-register-agent-modal" in your config

4. Wallet Setup (Step 3): Copy PRIVY_APP_ID and PRIVY_WALLET_ID values

5. Final Configuration: Copy the ESCROW_ADDRESS (your wallet address) from the final step

Key Types Generated

PGP Keys (Required for Type 1 and Type 2): Used for encrypting transaction manifests and securing communication between components. Always generated with passphrase protection.

P-256 Keys (Required for Type 2 only): ECDSA keys used for agent transaction signing via Privy. Uses Base64 format for PRIVY_EXECUTION_PRIVATE_KEY. Not needed for Type 1 where you sign transactions yourself.

Full Working Example: The Claude Agent Quickstart demonstrates a complete Type 2 (AGENT_EXECUTED) setup with step-by-step instructions for key generation, Nava registration, and Privy wallet configuration.

Configuration

This adapter uses Privy for wallet integration. The easiest way to get started is to use the key generation tool which creates a complete mcp-config.json file for you.

Fireblocks Integration: We support Fireblocks wallet integration. Please contact us to set up Fireblocks for your deployment.

Environment Variables Reference

Common (Required for all configurations)

• MODE: "external" or "self-custodial" - Execution mode
• NAVA_API_KEY: API key from RegisterAgentModal Step 1
• NAVA_BASE_URL: Nava service URL (e.g., http://localhost:3001)
• CHAIN_ID: Blockchain network ID (e.g., "11155111" for Sepolia)
• RPC_URL: Blockchain RPC endpoint (e.g., Alchemy, Infura)
• NAVA_INBOX_ADDRESS: Nava inbox contract address
• ESCROW_ADDRESS: Your escrow contract address from RegisterAgentModal Step 4
• EXECUTION_TYPE: "1" (user-executed, recommended) or "2" (agent-executed) or "0" (direct)
• PGP_ARBITER_PUBLIC_KEY: Arbiter's public PGP key from RegisterAgentModal Step 2
• PGP_EXECUTOR_PRIVATE_KEY: Your PGP private key (generated by key tool)
• PGP_EXECUTOR_PASSPHRASE: Passphrase for your PGP key

Privy-Specific (Required for Type 2)

• PRIVY_APP_ID: Application ID from RegisterAgentModal Step 3
• PRIVY_WALLET_ID: Wallet ID from RegisterAgentModal Step 3
• PRIVY_EXECUTION_PRIVATE_KEY: P-256 private key for signing in Base64 format (generated by key tool)

Self-Custodial Mode (additional requirements)

• PINATA_JWT: Pinata JWT token for IPFS storage
• PINATA_GATEWAY: Pinata gateway URL
• NAVA_RPC_URL: Nava blockchain RPC endpoint
• SELF_CUSTODIAL_PRIVATE_KEY: Private key for self-custodial execution

Automated Configuration

Use the key generation tool to create a complete configuration:

# This creates mcp-config.json with all your keys pre-configured
pnpm generate-escrow-keys privy mypassphrase

After generation, you only need to replace the placeholder values marked with "your-*" using values from the RegisterAgentModal.

Manual Configuration (Alternative)

If you prefer manual setup or need to understand the configuration structure, you can examine the generated mcp-config.json file structure after running the key generation tool once.

Completing Your Generated Configuration

After running the key generation command, you'll have a mcp-config.json file with your keys already configured. You just need to replace the placeholder values using the RegisterAgentModal:

Step 1: Get API Credentials

• Open the RegisterAgentModal in your browser
• In Step 1, copy the NAVA_API_KEY value
• Replace "your-nava-api-key-from-register-agent-modal" in your config

Step 2: Register Your PGP Key

• Copy your PGP public key from the terminal output (displayed after key generation)
• Paste it into the Step 2: PGP Registration in the RegisterAgentModal
• Copy the PGP_ARBITER_PUBLIC_KEY value that appears
• Replace "pgp-arbiter-key-from-register-agent-modal" in your config

Step 3: Privy Wallet Setup

• Complete the Privy quorum setup in Step 3 of the RegisterAgentModal
• Copy the PRIVY_APP_ID and PRIVY_WALLET_ID values
• Replace the corresponding placeholders in your config

Step 4: Final Configuration

• Copy the ESCROW_ADDRESS from the final step (your wallet address)
• Replace "your-wallet-address-from-register-agent-modal" in your config
• Update RPC_URL with your Alchemy API key if needed

Security Notes

• Keys are displayed in terminal only - No files are written to disk for security
• Never commit mcp-config.json - Add it to your .gitignore file
• Store private keys securely - The generated config contains real private keys
• Use strong passphrases - PGP keys are encrypted with your passphrase

Configuration Structure

The generated mcp-config.json file includes:

• Complete MCP server definition with proper command and arguments
• All generated keys properly formatted with escaped newlines
• Wallet-specific environment variables (no cross-contamination)
• Placeholder values clearly marked for replacement

Execution Type Examples

The MCP adapter supports three execution types through the EXECUTION_TYPE environment variable. Each type requires different configuration fields.

Type 1: USER_EXECUTED (Recommended)

User-executed with arbiter review. The arbiter verifies the transaction, but the user executes it through their own wallet.

Configuration:

{
  "mcpServers": {
    "execution-escrow": {
      "command": "node",
      "args": ["/path/to/mcp-adapter/dist/index.js"],
      "env": {
        "MODE": "external",
        "EXECUTION_TYPE": "1",
        "ESCROW_ADDRESS": "0x...",
        "CHAIN_ID": "11155111",
        "NAVA_API_KEY": "nava_live_...",
        "PGP_EXECUTOR_PRIVATE_KEY": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n...",
        "PGP_EXECUTOR_PASSPHRASE": "your_passphrase"
      }
    }
  }
}

Note: Type 1 requires PGP keys for encryption but does not require RPC URL or wallet credentials since the user provides execution via their wallet.

Type 2: AGENT_EXECUTED

Agent-executed with arbiter review. The arbiter verifies the transaction and the agent automatically executes approved transactions.

Configuration (Privy):

{
  "mcpServers": {
    "execution-escrow": {
      "command": "node",
      "args": ["/path/to/mcp-adapter/dist/index.js"],
      "env": {
        "MODE": "external",
        "EXECUTION_TYPE": "2",
        "ESCROW_ADDRESS": "0x...",
        "CHAIN_ID": "11155111",
        "NAVA_API_KEY": "nava_live_...",
        "PGP_EXECUTOR_PRIVATE_KEY": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n...",
        "PGP_EXECUTOR_PASSPHRASE": "your_passphrase",
        "RPC_URL": "https://eth-sepolia.g.alchemy.com/v2/...",
        "PRIVY_WALLET_ID": "did:privy:...",
        "PRIVY_EXECUTION_PRIVATE_KEY": "MIGHAgEAMBMG..."
      }
    }
  }
}

Note: Type 2 requires full configuration including RPC URL and Privy wallet credentials for autonomous execution.

Fireblocks Integration: We support Fireblocks wallet integration for Type 2 execution. Please contact us to set up Fireblocks for your deployment.

Type 0: DIRECT_USER

Minimal configuration for direct user execution with no arbiter review. The user signs all transactions themselves.

Configuration:

{
  "mcpServers": {
    "execution-escrow": {
      "command": "node",
      "args": ["/path/to/mcp-adapter/dist/index.js"],
      "env": {
        "MODE": "external",
        "EXECUTION_TYPE": "0",
        "ESCROW_ADDRESS": "0x...",
        "CHAIN_ID": "11155111",
        "NAVA_API_KEY": "nava_live_..."
      }
    }
  }
}

Note: Type 0 does not require PGP keys, RPC URL, or wallet credentials since the user executes through their own wallet.

Optional Fields (SDK Defaults)

The following fields have SDK-provided defaults and can be omitted unless you need to override them:

• NAVA_BASE_URL - Defaults to https://api.nava.dev
• NAVA_INBOX_ADDRESS - Defaults to official Nava Inbox contract address
• PGP_ARBITER_PUBLIC_KEY - Defaults to official arbiter public key
• PRIVY_APP_ID - Defaults to Nava Privy application ID

Example with optional overrides:

{
  "env": {
    // ... required fields above ...
    "NAVA_BASE_URL": "http://localhost:3001",
    "NAVA_INBOX_ADDRESS": "0xcustom...",
    "PGP_ARBITER_PUBLIC_KEY": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n..."
  }
}

For more details on execution types, see the SDK documentation.

Execution Modes

This adapter supports two execution modes:

External Mode (Default)

The default configuration uses external execution through the Nava service. This is the recommended mode for most users as it provides:

• Managed infrastructure
• Professional arbiter verification
• No requirement for self-managed blockchain infrastructure

Self-Custodial Mode

For self-custodial mode, manually add these environment variables to your generated config:

"MODE": "self-custodial",
"PINATA_JWT": "your-pinata-jwt",
"PINATA_GATEWAY": "your-pinata-gateway",
"NAVA_RPC_URL": "your-nava-rpc-url",
"SELF_CUSTODIAL_PRIVATE_KEY": "0x..."

Mode Values:

• "external" - Uses Nava service for execution (default, recommended)
• "self-custodial" - Self-managed execution with your own blockchain infrastructure

Usage

Basic Usage

import { createMCPServer } from '@navalabs/execution-escrow-adapter';

// Create server (auto-configures from environment)
const server = createMCPServer();

// Initialize
await server.initialize();

// Request verification
const result = await server.requestVerification({
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb4',
  value: '0.1', // ETH amount
  description: 'Payment for services',
  escrowAddress: '0x1234567890123456789012345678901234567890',
  data: '0x' // optional
});

if (result.success) {
  console.log('Request hash:', result.requestHash);
}

Direct Tool Usage

import { MCPRequestVerificationTool } from '@navalabs/execution-escrow-adapter';

const tool = new MCPRequestVerificationTool();
await tool.initialize();

const result = await tool.requestVerification({
  to: '0x...',
  value: '1.5',
  description: 'Transaction description',
  escrowAddress: '0x...'
});

MCP Integration

The tool exposes an MCP-compatible interface:

const tool = createMCPServer();
const toolDefinition = tool.getMCPTool();

// Tool definition for MCP registration
console.log(toolDefinition);
// {
//   name: 'requestVerification',
//   description: 'Request verification for a blockchain transaction',
//   inputSchema: { ... }
// }

// Handle MCP tool calls
const result = await tool.handleToolCall('requestVerification', params);

Tool Definition

Name

requestVerification

Input Parameters

Parameter	Type	Required	Description
to	string	Yes	Recipient address (0x-prefixed)
value	string	Yes	Amount in ETH or Wei
description	string	Yes	Transaction purpose description
escrowAddress	string	Yes	Escrow contract address
data	string	No	Transaction data (0x-prefixed hex)

Response

{
  success: boolean;
  requestHash?: string;  // Transaction request hash if successful
  message: string;       // Success or error message
  error?: string;        // Error details if failed
}

MCP Client Integration

To use this adapter with any MCP client (Claude Desktop, MCP Inspector, etc.), add it to your MCP client's configuration.

Complete Example: See the Claude Agent Quickstart for a fully working agent that uses this MCP adapter with the Claude Agent SDK and Foundry blockchain tools.

Using Local Installation (Recommended)

After installing the package in your project, reference the built adapter:

{
  "mcpServers": {
    "execution-escrow": {
      "command": "node",
      "args": ["./node_modules/@navalabs/execution-escrow-adapter/dist/mcp/index.js"],
      "env": {
        "NAVA_API_KEY": "nava_live_...",
        "ESCROW_ADDRESS": "0x...",
        "CHAIN_ID": "11155111",
        "RPC_URL": "https://eth-sepolia.g.alchemy.com/v2/...",
        "PGP_EXECUTOR_PRIVATE_KEY": "-----BEGIN PGP PRIVATE KEY BLOCK-----\\n...\\n-----END PGP PRIVATE KEY BLOCK-----",
        "PGP_EXECUTOR_PASSPHRASE": "your-passphrase",
        "PRIVY_WALLET_ID": "...",
        "PRIVY_EXECUTION_PRIVATE_KEY": "..."
      }
    }
  }
}

Using npx

Alternatively, you can use npx to run the adapter without a local installation:

{
  "mcpServers": {
    "execution-escrow": {
      "command": "npx",
      "args": ["@navalabs/execution-escrow-adapter"],
      "env": {
        // Your environment variables here
      }
    }
  }
}

Testing

The package includes a test tool (test-tool.ts) to verify functionality with your configuration.

Testing with MCP Inspector

To test your MCP configuration thoroughly, you can use the official MCP Inspector tool:

Step 1: Install MCP Inspector

npm install -g @modelcontextprotocol/inspector

Step 2: Build Your MCP Adapter

cd execution-escrow/packages/adapter
pnpm build

Step 3: Launch MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

The inspector will prompt you to configure environment variables. You can manually enter the values from your mcp-config.json file through the inspector's interface.

This will:

• Start a proxy server on localhost:6277
• Open a web interface with an authentication token
• Show real-time MCP communication
• Allow you to test tool execution interactively

Step 4: Test Your Configuration

In the MCP Inspector web interface, you can:

• Verify Server Connection: Confirm your MCP server starts without errors
• Inspect Available Tools: See the requestVerification tool definition
• Test Tool Execution: Call requestVerification with sample parameters
• Debug Environment: Verify all environment variables are correctly passed
• Monitor Communication: See real-time protocol messages between client and server

The inspector will show any configuration issues, missing environment variables, or runtime errors, making it the most effective way to validate your MCP setup.

Available Test Scripts

• pnpm test - Run unit tests

Note: The test tool requires all dependencies to be properly installed and configured. If you encounter missing dependency errors, ensure the core execution-escrow package has all optional dependencies installed for your wallet provider.

Cookbook Examples

Claude Agent Quickstart

The Claude Agent Quickstart demonstrates a fully functional AI agent using the Execution Escrow MCP adapter. This example includes:

• Claude Agent SDK integration - Interactive agent with conversation context
• Foundry MCP - Smart contract interaction tools (cast_call, cast_send, etc.)
• Execution Escrow MCP - Arbiter-verified transaction execution
• Type 2 (AGENT_EXECUTED) - Autonomous execution after arbiter approval

Architecture:

Claude Agent SDK
├── Foundry MCP (smart contract tools)
└── Execution Escrow MCP (verified transactions)

Quick Start:

git clone https://github.com/navalabs-dev/cookbook.git
cd cookbook/claude-agent
pnpm install
cp .env.example .env
cp mcp-config.example.json mcp-config.json
# Configure your credentials in .env and mcp-config.json
pnpm build && pnpm start

Example mcp-config.json:

{
  "mcpServers": {
    "execution-escrow": {
      "command": "npx",
      "args": ["@navalabs/execution-escrow-adapter"],
      "env": {
        "NAVA_API_KEY": "nava_live_your-api-key",
        "ESCROW_ADDRESS": "0x...your-safe-wallet-address",
        "CHAIN_ID": "11155111",
        "RPC_URL": "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
        "PGP_EXECUTOR_PRIVATE_KEY": "-----BEGIN PGP PRIVATE KEY BLOCK-----\\n...\\n-----END PGP PRIVATE KEY BLOCK-----",
        "PGP_EXECUTOR_PASSPHRASE": "your-passphrase",
        "PRIVY_WALLET_ID": "your-privy-wallet-id",
        "PRIVY_EXECUTION_PRIVATE_KEY": "your-base64-p256-key"
      }
    }
  }
}

See the full README for detailed setup instructions, troubleshooting, and customization options.