bind-mcp

Bind Protocol MCP 服务器用于凭证验证、策略编写和零知识证明生成。

## 概述（中文）

Bind Protocol MCP 服务器用于凭证验证、策略编写和零知识证明生成。

## 原文

# Bind MCP Server — Agent Skill Guide

You have access to the Bind Protocol MCP server. This document teaches you how to use it.

## Prerequisites & Installation

### Requirements

- **Node.js >= 18** — Required to run the server (`npx` handles package installation automatically)
- **Bind account** — Required for API-backed tools. Create one at https://dashboard.bindprotocol.xyz
- **Agent key** (`idbr_agent_...`) — Required for API-backed tools. Regular API keys (`idbr_`) are not supported for MCP.

### Credential Setup

Bind uses **agent keys** for MCP authentication. Agent keys are scoped API keys that let org admins control exactly which tools are available, set daily rate limits, and get audit logs.

| Key type | Format | MCP supported |
|----------|--------|---------------|
| **Agent key** | `idbr_agent_<keyId>_<secret>` | Yes — required for API-backed tools |
| **Regular API key** | `idbr_<keyId>_<secret>` | No — rejected by MCP server |

To create an agent key:
1. Sign in at https://dashboard.bindprotocol.xyz
2. Navigate to **Settings > Agent Keys**
3. Select which tool categories the key can access (e.g., credential verification only, or policy authoring + verification)
4. Copy the key — it is shown only once

### MCP Server Configuration

Add the server to your MCP client configuration. The exact file depends on your tool:

| Tool | Config file |
|------|------------|
| Claude Code | `.mcp.json` in your project root, or `~/.claude/claude_desktop_config.json` |
| Claude Desktop | Settings > Developer > Edit Config |
| Cursor | `.cursor/mcp.json` in your project root |
| Windsurf | MCP settings |

**Configuration JSON:**

```json
{
  "mcpServers": {
    "bind": {
      "command": "npx",
      "args": ["@bind-protocol/mcp-server"],
      "env": {
        "BIND_API_KEY": "${BIND_API_KEY}"
      }
    }
  }
}
```

The `BIND_API_KEY` environment variable must be set in your shell to your agent key before launching your AI tool. **Never hardcode the key directly in config files** — always use environment variable references to avoid accidental credential leakage in shared configs or repositories.

**Environment variables:**

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BIND_API_KEY` | For API-backed tools | — | Agent key (`idbr_agent_...`). Without this, only local tools are available. |
| `BIND_API_URL` | No | `https://api.bindprotocol.xyz` | Base URL for API calls |
| `BIND_RECEIPTS_PATH` | No | `~/.bind/receipts` | Directory for receipt chain data |
| `LOG_LEVEL` | No | `info` | Logging verbosity (`debug`, `info`, `warn`, `error`) |

### Verifying the Setup

If you do not have `bind` tools available, prompt the user to complete the setup above. You can test connectivity by calling `bind_whoami` — if it returns org info, the agent key is authenticated. Without a `BIND_API_KEY`, only local tools (parse, verify, hash) are available.

---

## Architecture & Data Flow

The server runs locally via `npx` and communicates with your AI tool over stdio. It provides both local tools (always available) and API-backed tools (require an agent key). You just call the tool by name — routing is handled automatically.

| Tool type | Auth | Purpose |
|-----------|------|---------|
| **Local tools** | None | Parse, verify, and hash VC-JWTs on-device |
| **API-backed tools** | Agent key via `BIND_API_KEY` | Policies, proofs, issuers, revocation, and more |

### What stays local vs. what calls the API

This is critical for understanding the privacy model:

**Local tools (credential data NEVER leaves the machine):**
- `bind_parse_credential` — Decodes the JWT entirely on your machine
- `bind_verify_credential` — Fetches the issuer's public JWKS from the Bind API (public keys only), then verifies the signature locally. The credential itself is never sent.
- `bind_hash_credential` — Computes a SHA-256 hash locally. Only the irreversible hash is used for revocation checks.

**API-backed tools (send requests to `api.bindprotocol.xyz`):**
- `bind_check_revocation` — Sends only the credential **hash** (not the credential). The hash is not reversible.
- `bind_resolve_issuer` — Fetches public keys for an org. No credential data involved.
- `bind_explain_policy`, `bind_list_policies`, `bind_list_circuits` — Read-only public metadata. No credential data involved.
- `bind_submit_prove_job` — Sends circuit inputs to the Bind proving service. These are the raw values being proven (e.g., income amount, mileage count).
- `bind_issue_credential` — Requests the Bind API to sign and issue a VC-JWT from a completed proof.
- `bind_create_policy`, `bind_validate_policy` — Sends policy spec JSON to Bind for validation/storage.
- `bind_share_proof` — Shares a proof record with a verifier org via the Bind API.

**In short:** Raw credentials are local-only. Hashes, policy specs, proof inputs, and metadata go to the API.

---

## Tool Inventory

### Local Tools (no auth required, credential data stays on-machine)

| Tool | What it does |
|------|-------------|
| `bind_parse_credential` | Decode a VC-JWT into header + payload + signature without verification |
| `bind_verify_credential` | Full verification: parse, fetch issuer JWKS, verify ES256 signature, check expiration. Does NOT check revocation. |
| `bind_hash_credential` | SHA-256 hash a VC-JWT. Use the hash with `bind_check_revocation`. |

### API-Backed Tools (require agent key via `BIND_API_KEY`)

**Discovery & Inspection**

| Tool | What it does |
|------|-------------|
| `bind_resolve_issuer` | Fetch an org's public signing keys (JWKS) by org ID |
| `bind_explain_policy` | Get the public spec for a policy by policy ID |
| `bind_check_revocation` | Check if a credential is revoked by its hash (hash only — not the credential) |
| `bind_list_policies` | List available policies (supports `limit`/`offset` pagination) |
| `bind_list_circuits` | List available ZK circuits |

**Proof Generation & Credential Issuance**

| Tool | What it does |
|------|-------------|
| `bind_submit_prove_job` | Submit a ZK proof generation job with circuit ID and inputs |
| `bind_get_prove_job` | Poll a prove job's status by job ID |
| `bind_list_prove_jobs` | List prove jobs, optionally filtered by status |
| `bind_issue_credential` | Issue a verifiable credential from a completed prove job |
| `bind_share_proof` | Share a completed proof with a verifier org |
| `bind_list_shared_proofs` | List proofs shared with/by your org |

**Policy Authoring**

| Tool | What it does |
|------|-------------|
| `bind_whoami` | Get authenticated org info, tier, policy limits, and agent key permissions |
| `bind_validate_policy` | Dry-run validation of a policy spec (catches errors before creation) |
| `bind_create_policy` | Create a new verification policy |
| `bind_generate_circuit` | Trigger ZK circuit compilation for a saved policy |
| `bind_get_circuit_status` | Poll circuit compilation job status |

---

## Workflow 1: Full Credential Verification

**When to use:** A user gives you a VC-JWT string (starts with `eyJ...`) and wants to know if it's valid.

**Steps:**

1. `bind_parse_credential` — Decode the JWT to inspect claims
2. `bind_verify_credential` — Verify signature and expiration
3. `bind_hash_credential` — Compute SHA-256 hash
4. `bind_check_revocation` — Send the hash (not the credential) to check revocation

Steps 1 and 2 can be combined (verify includes parsing), but parsing first lets you show the user what the credential contains before the full check. Steps 1–3 run locally; step 4 sends only the hash to the API.

**Important:** `bind_verify_credential` does NOT check revocation. You must always follow up with hash + revocation check for a complete verification.

```
parse → verify → hash → check_revocation
```

## Workflow 2: Investigate an Issuer

**When to use:** A user wants to know about an organization's keys or policies.

1. `bind_res