MCP Server

The DPO2U MCP (Model Context Protocol) Server exposes standardized tools that allow any AI agent (like Claude, ChatGPT, or custom frameworks) to natively interact with the Midnight blockchain and the DPO2U infrastructure.

Core availability

The server translates complex web3 logic (wallet handling, IPFS resolution, Compact smart contract querying) into simple callable functions that language models inherently understand.

Primary use case

An AI Agent in a Fintech company needs to send a dossier to a partner provider. Before transferring the data, the AI calls the DPO2U MCP Server to verify if the partner is currently compliant. If the boolean compliant flag returns false, the AI autonomously aborts the transfer, ensuring zero-trust privacy boundaries.

Authentication

All requests require a Bearer token in the Authorization header. API keys are issued per organization through the DPO2U dashboard.

Authorization: Bearer dpo2u_sk_live_xxxxxxxxxxxx

API key scopes

Keys are scoped to specific tools. A read-only key can call check_compliance_status but cannot trigger generate_lgpd_kit. Request the appropriate scope when creating your key.

Exposed tools

1. check_compliance_status

Checks the on-chain compliance status of a specific company.

Input:

{
  "company_id": "string (CNPJ or unique identifier hash)"
}

Returns:

{
  "compliant": true,
  "score": 87,
  "last_validated": "2026-02-28T14:30:00Z",
  "proof_url": "https://explorer.midnight.network/tx/0xabc..."
}

curl example:

curl -X POST https://mcp.dpo2u.com/tools/check_compliance_status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DPO2U_API_KEY" \
  -d '{"company_id": "hashed-cnpj-identifier"}'

2. generate_lgpd_kit

Triggers the Expert Agent to generate an entire LGPD kit for a given company profile.

Input:

{
  "companyProfile": {
    "name": "string",
    "sector": "string",
    "dataProcessed": ["string"]
  }
}

Returns:

{
  "policy_json": { "...LGPDPolicy bound to dpo2u/lgpd/v1 schema" },
  "documents": [
    { "type": "privacy_policy", "cid": "bafybeig...", "url": "https://..." },
    { "type": "dpia", "cid": "bafybeih...", "url": "https://..." }
  ]
}

curl example:

curl -X POST https://mcp.dpo2u.com/tools/generate_lgpd_kit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DPO2U_API_KEY" \
  -d '{
    "companyProfile": {
      "name": "Acme Corp",
      "sector": "fintech",
      "dataProcessed": ["customer_pii", "transaction_history"]
    }
  }'

3. register_document

Uploads a Base64-encoded document to the Lighthouse IPFS network.

Input:

{
  "document": "string (Base64-encoded file content)",
  "metadata": {
    "filename": "string",
    "content_type": "application/pdf",
    "company_id": "string"
  }
}

Returns:

{
  "cid": "bafybeig...",
  "url": "https://gateway.lighthouse.storage/ipfs/bafybeig..."
}

curl example:

curl -X POST https://mcp.dpo2u.com/tools/register_document \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DPO2U_API_KEY" \
  -d '{
    "document": "JVBERi0xLjQK...",
    "metadata": {
      "filename": "privacy-policy.pdf",
      "content_type": "application/pdf",
      "company_id": "hashed-cnpj-identifier"
    }
  }'

Error handling

The MCP Server returns standard HTTP status codes with structured error bodies:

Status	Meaning	Common cause
200	Success	Tool executed successfully
400	Bad Request	Missing or invalid input parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks the required scope for this tool
404	Not Found	Company ID has no on-chain Attestation
429	Rate Limited	Too many requests (see rate limiting below)
500	Internal Error	Server-side failure — retry with exponential backoff

Error response format:

{
  "error": {
    "code": "INVALID_COMPANY_ID",
    "message": "The provided company_id does not match any on-chain record.",
    "tool": "check_compliance_status"
  }
}

Rate limiting

Tier	Requests/min	Burst
Free	10	20
Standard	60	120
Enterprise	300	600

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Local development

To test tool calls without connecting to production:

# Clone and install
git clone https://github.com/dpo2u/mcp-server.git
cd mcp-server
npm install

# Configure environment
cp .env.example .env
# Edit .env: set MIDNIGHT_RPC_URL to testnet, LIGHTHOUSE_API_KEY, etc.

# Start the server
npm run dev
# Server listening on http://localhost:3100

# Test a tool call
curl -X POST http://localhost:3100/tools/check_compliance_status \
  -H "Content-Type: application/json" \
  -d '{"company_id": "test-company-hash"}'

What's next

• Getting Started — quick setup and first API call
• Schemas — the dpo2u/lgpd/v1 schema that generate_lgpd_kit produces
• Agents — the autonomous agents that power MCP tool execution