@sardis/mcp-server

Model Context Protocol (MCP) server for Sardis - Enable AI agents to execute secure payments with Financial Hallucination Prevention

Table of Contents

• Quick Start
• What is this?
• Installation
• Available Tools
• Policy Engine
• Example Session
• Environment Variables
• Simulated Mode
• API Reference
• License

Quick Start

npx @sardis/mcp-server start

What is this?

Sardis MCP Server allows AI agents (Claude, Cursor, etc.) to execute payments through your Sardis wallet using the Model Context Protocol. It provides Financial Hallucination Prevention through natural language spending policies.

Installation

Option 1: npx (Recommended)

No installation required - run directly:

npx @sardis/mcp-server start

Option 2: Global Install

npm install -g @sardis/mcp-server
sardis-mcp start

Option 3: Local Install

npm install @sardis/mcp-server
npx sardis-mcp start

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

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

Minimal Configuration (Simulated Mode)

{
  "mcpServers": {
    "sardis": {
      "command": "npx",
      "args": ["@sardis/mcp-server", "start"]
    }
  }
}

Production Configuration

{
  "mcpServers": {
    "sardis": {
      "command": "npx",
      "args": ["@sardis/mcp-server", "start"],
      "env": {
        "SARDIS_API_KEY": "sk_live_your_api_key_here",
        "SARDIS_WALLET_ID": "wal_your_wallet_id",
        "SARDIS_MODE": "live"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json or Cursor settings):

Minimal Configuration

{
  "mcpServers": {
    "sardis": {
      "command": "npx",
      "args": ["@sardis/mcp-server", "start"]
    }
  }
}

Production Configuration

{
  "mcpServers": {
    "sardis": {
      "command": "npx",
      "args": ["@sardis/mcp-server", "start"],
      "env": {
        "SARDIS_API_KEY": "sk_live_your_api_key_here",
        "SARDIS_WALLET_ID": "wal_your_wallet_id",
        "SARDIS_MODE": "live"
      }
    }
  }
}

Other MCP Clients

For any MCP-compatible client, use:

• Command: npx
• Arguments: ["@sardis/mcp-server", "start"]
• Transport: stdio

Available Tools (36 total)

Wallet Tools (5)

Payment Tools (3)

Policy Tools (3)

Hold Tools (6)

Agent Tools (4)

Card Tools (6)

Fiat Tools (4)

Approval Tools (2)

Spending Analytics Tools (3)

Policy Engine

The server validates all payments against your configured spending policy:

• Allowed Categories: SaaS, DevTools, Cloud, API
• Blocked Merchants: Configurable blocklist
• Transaction Limits: Max per transaction and daily limits
• Risk Scoring: Each request gets a risk score
• Approval Workflows: Human-in-the-loop for high-value transactions

Example Session

Agent: I need to pay $20 for OpenAI API credits

[sardis_pay] vendor="OpenAI", amount=20, purpose="API Credits"

Result: {
  "success": true,
  "status": "APPROVED",
  "card": {
    "number": "4242 **** **** 9999",
    "cvv": "847",
    "expiry": "12/26"
  }
}

Agent: Can I buy a $500 Amazon gift card?

[sardis_pay] vendor="Amazon", amount=500

Result: {
  "success": false,
  "status": "BLOCKED",
  "error": "POLICY_VIOLATION",
  "message": "Merchant \"Amazon\" is not in the approved vendor list",
  "prevention": "Financial Hallucination PREVENTED"
}

Agent: What's my spending this month?

[sardis_get_spending_summary] period="month"

Result: {
  "total_spent": "450.00",
  "transaction_count": 12,
  "remaining_daily_limit": "50.00",
  "remaining_monthly_limit": "550.00",
  "top_vendor": "OpenAI"
}

Environment Variables

Getting Your API Key

1. Sign up at sardis.sh
2. Go to Settings > API Keys
3. Create a new API key with appropriate permissions
4. Add it to your MCP configuration

Simulated Mode

When running without an API key, the server operates in simulated mode with:

• Mock wallet with $1000 balance
• Simulated transactions that don't execute on-chain
• Full policy validation to test your rules
• Realistic response formats

API Reference

Tools Schema

Each tool follows the MCP tool specification:

interface Tool {
  name: string;
  description: string;
  inputSchema: JSONSchema;
}

Common Parameters

Response Format

All tools return responses in this format:

interface ToolResponse {
  success: boolean;
  status: 'APPROVED' | 'BLOCKED' | 'PENDING' | 'ERROR';
  data?: Record<string, unknown>;
  error?: string;
  message?: string;
}

Requirements

• Node.js 18.0.0 or higher
• Claude Desktop, Cursor, or any MCP-compatible client

Troubleshooting

Server not starting

1. Ensure Node.js 18+ is installed: node --version
2. Clear npx cache: npx clear-npx-cache
3. Try global install: npm install -g @sardis/mcp-server

Tools not appearing in Claude

1. Restart Claude Desktop after configuration changes
2. Check the configuration file path is correct for your OS
3. Verify JSON syntax is valid

API errors

1. Check your API key is valid
2. Ensure SARDIS_MODE is set to live for production
3. Verify wallet ID exists in your account

Support

• Documentation
• GitHub Issues
• Discord Community
• Email: support@sardis.sh

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.