io.github.chudah1/attest-mcp

Attest

Attest controls and proves risky AI actions before they hit production systems. It gives agents signed, scope-limited credentials, routes high-risk mutations through policy and optional approval, issues short-lived execution grants, and leaves signed receipts that can be verified later.

This repository also includes a standalone MCP server:

• TypeScript MCP server — a real stdio Model Context Protocol server that exposes Attest tools like issue_credential, delegate_credential, list_tasks, get_audit_trail, get_evidence, and approval actions.
• TypeScript MCP middleware — middleware for protecting your own MCP server with Attest.

Quickstart (TypeScript)

import { AttestClient } from '@attest-dev/sdk';

const client = new AttestClient({ baseUrl: 'http://localhost:8080', apiKey: 'dev' });

// 1. Issue a root credential for your agent workflow
const root = await client.issue({
  agent_id: 'support-bot',
  user_id: 'alice@acme.com',
  scope: ['refund:execute', 'credit:execute'],
  instruction: 'Review support incidents and safely process eligible refunds.',
});

// 2. Request a risky action before touching the target system
const action = await client.requestAction({
  action_type: 'refund',
  target_system: 'stripe',
  target_object: 'order_ORD-4821',
  action_payload: {
    amount_cents: 4799,
    currency: 'USD',
    reason: 'damaged_item',
  },
  agent_id: 'support-bot',
  sponsor_user_id: 'alice@acme.com',
  att_tid: root.claims.att_tid,
});

if (action.status !== 'approved' || !action.grant?.token) {
  throw new Error(`refund needs approval: ${action.status}`);
}

// 3. Execute with the short-lived grant, then record the receipt
const receipt = await client.executeAction(action.id, {
  outcome: 'success',
  provider_ref: 're_abc123',
  response_payload: { stripe_status: 'succeeded' },
});
console.log(receipt.signed_packet_hash);

// 4. Fetch the immutable receipt later
const confirmed = await client.getReceipt(action.id);
console.log(confirmed.outcome, confirmed.provider_ref);

Scope syntax

Scopes follow the pattern resource:action. Either field may be * as a wildcard.

Delegation still enforces that child scope is a strict subset of the parent scope. The Action API builds on top of that delegation substrate to gate risky writes.

Getting started

Prerequisites: Docker and Docker Compose.

# Clone and start everything
git clone https://github.com/chudah1/attest-dev
cd attest-dev
docker compose up --build

# The server is now running at http://localhost:8080
# PostgreSQL at localhost:5432

# Issue your first credential (replace YOUR_API_KEY with the key from POST /v1/orgs)
curl -s -X POST http://localhost:8080/v1/credentials \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "agent_id":    "orchestrator-v1",
    "user_id":     "usr_alice",
    "scope":       ["research:read", "gmail:send"],
    "instruction": "Research competitors and email the board"
  }' | jq .

# Open the interactive demo
open demo/index.html

If you want to run the Go server outside Docker, point it at the Compose database:

docker compose up -d postgres
cd server
DATABASE_URL=postgres://attest:attest@localhost:5432/attest go run ./cmd/attest

API reference

Specification

The credential format is defined in spec/WCS-01.md (Attest Credential Standard, revision 01).

License

Apache 2.0 — see LICENSE.