MCP Server

Let AI agents create reviews, submit attestations, and verify proofs via the Model Context Protocol.

The @proofofhuman/mcp-server package exposes the Blanc API as MCP tools, allowing AI agents (Claude, Cursor, Copilot, etc.) to programmatically create reviews, submit evidence, and verify attestations.

Installation

npm install @proofofhuman/mcp-server

Or run directly:

npx @proofofhuman/mcp-server

Configuration

The server uses environment variables for configuration. On Vercel deployments, the base URL is auto-detected from system environment variables (VERCEL_PROJECT_PRODUCTION_URL, VERCEL_BRANCH_URL, VERCEL_URL).

Variable	Required	Default	Description
`PROOFOFHUMAN_API_KEY`	No	—	Your Blanc API key. Omit to use free tier (50 reviews/month).
`PROOFOFHUMAN_BASE_URL`	No	Auto-detected	Explicit override for the API base URL. Falls back to Vercel env vars, then `http://localhost:3000`.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "proofofhuman": {
      "type": "stdio",
      "command": "npx",
      "args": ["@proofofhuman/mcp-server"],
      "env": {
        "PROOFOFHUMAN_API_KEY": "your-api-key",
        "PROOFOFHUMAN_BASE_URL": "https://your-api.com"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "proofofhuman": {
      "command": "npx",
      "args": ["@proofofhuman/mcp-server"],
      "env": {
        "PROOFOFHUMAN_API_KEY": "your-api-key",
        "PROOFOFHUMAN_BASE_URL": "https://your-api.com"
      }
    }
  }
}

Tools

create-review

Create a new human review session for a document. Provide either document_content (the server computes the SHA-256 hash) or a pre-computed document_hash.

Parameters:

Name	Type	Required	Description
`document_content`	`string`	No*	Raw document content — the server computes the SHA-256 hash. Use for convenience.
`document_hash`	`string`	No*	Pre-computed SHA-256 hash. Use for privacy when content shouldn't leave your machine.
`document_title`	`string`	No	Human-readable title
`criteria_profile_id`	`string`	No	ID of the criteria profile (defaults to General Review on free tier)
`reviewer_id`	`string`	No	Assigned reviewer ID

* One of document_content or document_hash is required.

Returns: Review ID, document hash, status, criteria, review token, and expiry.

get-review

Get the current status and details of a review session.

Parameters:

Name	Type	Required	Description
`review_id`	`string`	Yes	The review session ID

Returns: Full review state including criteria, document info, and attestation ID if completed.

submit-attestation

Submit review evidence for a review session. Evidence is validated against the criteria profile.

Parameters:

Name	Type	Required	Description
`review_id`	`string`	Yes	The review session ID
`timeSpentSeconds`	`number`	Yes	Seconds spent reviewing
`scrollPercentage`	`number`	Yes	Max scroll depth (0-100)
`presenceVerified`	`boolean`	Yes	Whether presence was verified
`sectionsAcknowledged`	`string[]`	Yes	Sections the reviewer acknowledged
`comment`	`string`	Yes	Reviewer's comment

Returns: Attestation with ID, signature, evidence hash, and verification status.

verify-attestation

Verify the cryptographic integrity of an attestation.

Parameters:

Name	Type	Required	Description
`attestation_id`	`string`	Yes	The attestation ID

Returns: Validity status, attestation details, and verification breakdown.

create-action

Create a human approval request for an agent action (HITL). The human will review the action details on Blanc and approve or reject. Optionally provide a callback_url to receive the decision via webhook.

Parameters:

Name	Type	Required	Description
`action_type`	`string`	Yes	Type of action (e.g. `bank_transfer`, `deployment`, `data_deletion`)
`action_params`	`object`	Yes	Structured parameters for the action
`risk_level`	`string`	No	`low`, `medium`, `high`, or `critical`. Defaults to `medium`.
`callback_url`	`string`	No	URL to receive a webhook POST with the decision and signed attestation
`context`	`string`	No	Human-readable explanation of why the agent wants to perform this action
`title`	`string`	No	Short title for the action review
`criteria_profile_id`	`string`	No	Optional criteria profile override

Returns: Action ID, review URL, status, action type, risk level, review token, and expiry.

Example usage:

Agent: I need to transfer $15,000 from acct_001 to acct_002.
       Let me get human approval first.

→ create-action {
    "action_type": "bank_transfer",
    "action_params": { "from": "acct_001", "to": "acct_002", "amount": 15000 },
    "risk_level": "high",
    "callback_url": "https://your-app.com/webhooks/poh"
  }

← { "action_id": "uuid-abc123", "review_url": "https://...", "status": "pending" }

Agent: Waiting for human approval at the review URL...

→ get-action { "action_id": "uuid-abc123" }

← { "status": "completed", "decision": "approved", "attestation_id": "att_xyz789" }

Agent: Approved. Proceeding with the transfer.

get-action

Get the status and decision for an action approval request.

Parameters:

Name	Type	Required	Description
`action_id`	`string`	Yes	The action ID returned by `create-action`

Returns: Full action state including status, action type, parameters, risk level, decision (null while pending, "approved" or "rejected" once decided), and attestation ID if completed.

MCP Server

On this page