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.

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-mcp
# or
pnpm add @navalabs/execution-escrow-mcp

Quick Setup

Step 1: Generate Keys and Configuration

First, generate your cryptographic keys and MCP configuration file:

# For Privy wallet integration
npx @navalabs/execution-escrow-mcp generate-escrow-keys privy mypassphrase

# For Fireblocks wallet integration
npx @navalabs/execution-escrow-mcp generate-escrow-keys fireblocks mypassphrase

Note: If you're developing locally, you can also use:

pnpm exec tsx bin/generate-keys.ts 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

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:

Determine Desired Execution Type

EXECUTION_TYPE = 1 Your agents purposes a transaction, The orion agent verifies it, and then your agent executes it
EXECUTION_TYPE = 2 Your agent purposes and signs/initiates the transactions and the orion agent executes

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

For Fireblocks Wallets - Orion Executed Workflow - Configure Fireblocks API User This will create an API Key user within your fireblocks account that will be able to purpose transactions, This API Key User should have editor access. This step will allow our Orion Agent to pupose transactions after it validates the given parameters. This will be used by the Orion agent if you set EXECUTION_TYPE = 2 which enables orion to execute/create transactions on your behalf. Ultimately whether the transaction is executed depends on the policy that you grant to the API Key.

You can skip this step if you just want approval from the Orion agent and plan to perform exectuion.

Instructions:

Follow API User registration instructions
Once finished, ensure fireblocks connection is active using Test Connection button within Agent Registration Modal

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
Wallet Setup (Step 3):
- For Privy: Copy PRIVY_APP_ID and PRIVY_WALLET_ID values
- For Fireblocks: Populate FIREBLOCKS_API_KEY, FIREBLOCKS_VAULT_ACCOUNT_ID, and FIREBLOCKS_BASE_PATH with an API Key User for your agent. For FIREBLOCKS_SECRET_KEY we generated a key for your use but this can be retrieved from the fireblocks console.
Final Configuration: Copy the ESCROW_ADDRESS (your wallet address) from the final step

Key Types Generated

PGP Keys: Used for encrypting transaction manifests and securing communication between components. Always generated with passphrase protection.

P-256 Keys: ECDSA keys used for wallet integration:

Privy: Uses Base64 format for PRIVY_EXECUTION_PRIVATE_KEY
Fireblocks: Uses PEM format for FIREBLOCKS_SECRET_KEY

Configuration

This adapter supports two wallet providers: Privy and Fireblocks. The easiest way to get started is to use the key generation tool which creates a complete mcp-config.json file for you.

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) or "2" (agent-executed)
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 (when using Privy wallet)

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

Fireblocks-Specific (when using Fireblocks wallet)

FIREBLOCKS_API_KEY: API key from Fireblocks workspace (required)
FIREBLOCKS_VAULT_ACCOUNT_ID: Vault account ID (required)
FIREBLOCKS_BASE_PATH: "Sandbox", "US", "EU", or "EU2" (required)
FIREBLOCKS_SECRET_KEY: PEM-formatted private key for authentication (required, generated by key tool or from Fireblocks console)

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
npx @navalabs/execution-escrow-mcp generate-escrow-keys privy mypassphrase
# or
npx @navalabs/execution-escrow-mcp generate-escrow-keys fireblocks 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: Wallet-Specific Setup

For Privy:

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

For Fireblocks:

Get your Fireblocks API credentials from your workspace
Replace "your-fireblocks-api-key-here" with your actual API key

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 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-mcp';

// 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-mcp';

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:

Build the adapter:

cd execution-escrow/packages/mcp-adapter
pnpm build

Generate your configuration: Use the key generation tool to create your mcp-config.json configuration file, then replace placeholder values with actual values from the RegisterAgentModal

Add to your MCP client configuration: The configuration structure follows the MCP standard format:

{
  "mcpServers": {
    "execution-escrow": {
      "command": "node",
      "args": ["/absolute/path/to/execution-escrow/packages/mcp-adapter/dist/index.js"],
      "env": {
        // Your environment variables here
      }
    }
  }
}

Important: Update the args array with the absolute path to your built dist/index.js file.

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/mcp-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.

Overview​

Installation​

Quick Setup​

Step 1: Generate Keys and Configuration​

Step 2: Complete Configuration​

Key Types Generated​

Configuration​

Environment Variables Reference​

Common (Required for all configurations)​

Privy-Specific (when using Privy wallet)​

Fireblocks-Specific (when using Fireblocks wallet)​

Self-Custodial Mode (additional requirements)​

Automated Configuration​

Manual Configuration (Alternative)​

Completing Your Generated Configuration​

Step 1: Get API Credentials​

Step 2: Register Your PGP Key​

Step 3: Wallet-Specific Setup​

Step 4: Final Configuration​

Security Notes​

Configuration Structure​

Execution Modes​

External Mode (Default)​

Self-Custodial Mode​

Usage​

Basic Usage​

Direct Tool Usage​

MCP Integration​

Tool Definition​

Name​

Input Parameters​

Response​

MCP Client Integration​

Testing​

Testing with MCP Inspector​

Step 1: Install MCP Inspector​

Step 2: Build Your MCP Adapter​

Step 3: Launch MCP Inspector​

Step 4: Test Your Configuration​

Available Test Scripts​