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 Code, Cline, Gwen, Chatgpt)
A ViaHuman account

Installation

Via Claude Desktop

Open Claude Desktop settings
Navigate to Developer → Edit Config
Add the ViaHuman MCP server to your config:

{
  "mcpServers": {
    "viahuman": {
      "type": "http",
      "url": "https://mcp.viahuman.xyz/mcp",
      "timeout": 30000,
      "trust": true
    }
  }
}

Follow the authentication steps, and approve it on the viahuman consent page.

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

Best Practices

You can add these prompts in the .md file of your LLM of choice to make it use viahuman.

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

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

"Invalid API Key" Error

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

Approval Requests Not Received

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

Timeouts

Check your mobile device has internet connectivity
Increase the timeout_seconds value
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"