MCP Server Setup

Learn how to integrate ViaHuman with Model Context Protocol (MCP) servers for AI agent approvals.

What is MCP?

Model Context Protocol (MCP) is a standard for integrating AI assistants with external tools and data sources. The ViaHuman MCP server allows AI agents to request human approval before taking actions.

Prerequisites

  • An MCP-compatible AI assistant (e.g., Claude Desktop, Cline)
  • A ViaHuman account with an API key
  • Node.js 18+ installed

Installation

Via Claude Desktop

  1. Open Claude Desktop settings
  2. Navigate to Developer → Edit Config
  3. Add the ViaHuman MCP server to your config:
{
  "mcpServers": {
    "viahuman": {
      "command": "npx",
      "args": ["-y", "@viahuman/mcp-server"],
      "env": {
        "VIAHUMAN_API_KEY": "vh_live_your_api_key_here"
      }
    }
  }
}
  1. Restart Claude Desktop

Via Cline (VS Code)

  1. Open Cline settings in VS Code
  2. Go to MCP Servers
  3. Add a new server:
{
  "name": "viahuman",
  "command": "npx",
  "args": ["-y", "@viahuman/mcp-server"],
  "env": {
    "VIAHUMAN_API_KEY": "vh_live_your_api_key_here"
  }
}
  1. Restart VS Code

Available Tools

The ViaHuman MCP server provides the following tools:

1. request_approval

Request human approval before proceeding with an action.

Parameters:

  • title (required): Title of the approval request
  • description: Detailed description of what needs approval
  • context: Additional JSON context for the user
  • actions: Array of possible actions (default: ["approve", "reject"])
  • input_type: Type of input requested (none, text, number, select, image)
  • input_config: Configuration for the input type
  • timeout_seconds: Seconds to wait before timeout (default: 3600)

Example:

// AI agent requests approval to send an email
const approval = await requestApproval({
  title: "Send Email to Customer",
  description: "I want to send this email draft to the customer",
  context: {
    to: "customer@example.com",
    subject: "Re: Your Inquiry",
    body: "Thank you for reaching out..."
  },
  input_type: "text",
  input_config: {
    default_value: "Thank you for reaching out...",
    multiline: true
  }
});

if (approval.response_action === "approve") {
  // Send the email with approval.response_input as body
}

2. check_approval_status

Check the status of a pending approval.

Parameters:

  • approval_id (required): The UUID of the approval

Example:

const status = await checkApprovalStatus({
  approval_id: "uuid-here"
});

console.log(status.status); // "pending", "approved", "rejected", etc.

3. cancel_approval

Cancel a pending approval request.

Parameters:

  • approval_id (required): The UUID of the approval

Example:

await cancelApproval({
  approval_id: "uuid-here"
});

Usage Examples

Example 1: File Deletion Approval

User: "Delete all log files older than 30 days"

AI Agent:
- Scans directory and finds 127 log files
- Requests approval:
  Title: "Delete 127 log files?"
  Description: "Found 127 log files older than 30 days (total size: 2.3 GB)"
  Actions: ["approve", "reject", "review_list"]

User: *Receives notification on phone*
- Reviews file list
- Taps "Approve"

AI Agent:
- Receives approval
- Deletes the files
- Reports completion

Example 2: Budget Approval

User: "Book a hotel for the conference next month, budget is $300/night"

AI Agent:
- Searches hotels
- Finds best option: $350/night
- Requests approval:
  Title: "Approve Hotel Booking?"
  Description: "Found Marriott Downtown at $350/night (over budget by $50)"
  Input Type: number
  Default: 350
  Currency: USD

User: *Receives notification*
- Adjusts to $325/night
- Taps "Approve"

AI Agent:
- Receives approval with updated amount: $325
- Searches again with new budget
- Books approved hotel

Example 3: Code Deployment

User: "Deploy the latest changes to production"

AI Agent:
- Runs tests: ✓ All pass
- Builds project: ✓ Success
- Requests approval:
  Title: "Deploy to Production?"
  Description: "All tests passed. Ready to deploy v1.2.3"
  Input Type: select
  Options: [
    "production": "Deploy to Production",
    "staging": "Deploy to Staging first",
    "cancel": "Cancel deployment"
  ]

User: *Receives notification*
- Selects "staging"

AI Agent:
- Deploys to staging
- Runs smoke tests
- Requests second approval for production

Configuration Options

Environment Variables

Set these in your MCP server configuration:

  • VIAHUMAN_API_KEY (required): Your ViaHuman API key
  • VIAHUMAN_API_URL (optional): Custom API endpoint (default: https://api.viahuman.xyz)
  • VIAHUMAN_DEFAULT_TIMEOUT (optional): Default timeout in seconds (default: 3600)

Example Full Config

{
  "mcpServers": {
    "viahuman": {
      "command": "npx",
      "args": ["-y", "@viahuman/mcp-server"],
      "env": {
        "VIAHUMAN_API_KEY": "vh_live_your_api_key_here",
        "VIAHUMAN_API_URL": "https://api.viahuman.xyz",
        "VIAHUMAN_DEFAULT_TIMEOUT": "1800"
      }
    }
  }
}

Best Practices

When to Request Approval

✅ DO request approval for:

  • Irreversible actions (deletions, deployments)
  • Actions with financial impact
  • Sending external communications
  • Accessing sensitive data
  • Making changes to production systems

❌ DON'T request approval for:

  • Read-only operations
  • Routine automated tasks
  • Low-risk actions
  • Actions already explicitly authorized by the user

Providing Context

Always provide sufficient context in your approval requests:

// ❌ Bad: Not enough context
requestApproval({
  title: "Delete files?"
});

// ✅ Good: Clear context
requestApproval({
  title: "Delete 127 old log files?",
  description: "Found 127 log files older than 30 days (total: 2.3 GB)\nLocation: /var/log/myapp/\nOldest: 2024-01-15\nNewest: 2024-11-30",
  context: {
    file_count: 127,
    total_size_mb: 2300,
    directory: "/var/log/myapp"
  }
});

Handling Timeouts

Always handle timeout scenarios:

const approval = await requestApproval({
  title: "Deploy to Production?",
  timeout_seconds: 300  // 5 minutes
});

if (approval.status === "timeout") {
  console.log("Approval timed out. Deployment cancelled.");
  // Handle timeout gracefully
}

Error Handling

try {
  const approval = await requestApproval({
    title: "Dangerous Operation"
  });

  if (approval.response_action === "approve") {
    // Perform the operation
  } else {
    console.log("Operation rejected by user");
  }
} catch (error) {
  console.error("Approval request failed:", error);
  // Handle error gracefully
}

Troubleshooting

MCP Server Not Showing Up

  1. Check that the config file is valid JSON
  2. Restart your AI assistant (Claude Desktop, VS Code, etc.)
  3. Check the MCP server logs
  4. Verify Node.js 18+ is installed: node --version

"Invalid API Key" Error

  1. Verify your API key in the env config
  2. Ensure it starts with vh_live_
  3. Check the key is active in your dashboard

Approval Requests Not Received

  1. Ensure the ViaHuman mobile app is installed and logged in
  2. Check notification permissions
  3. Verify the API key belongs to the correct account
  4. Test with a simple API call to verify connectivity

Timeouts

  1. Check your mobile device has internet connectivity
  2. Increase the timeout_seconds value
  3. Verify the mobile app is in the foreground or has background refresh enabled

Example Prompts for AI Assistants

Here are some example prompts you can use with AI assistants that have the ViaHuman MCP server installed:

File Operations:

"Clean up my downloads folder, but ask me before deleting anything"

Email/Communication:

"Draft a response to this email and let me review it before sending"

Development:

"Deploy this fix to staging, then ask me before pushing to production"

Data Operations:

"Analyze this dataset and ask me which visualizations to generate"

Financial:

"Find the best flight option and ask me to approve the purchase"

Need Help?