Developer surfaces

Gateway, MCP, OTel, and n8n

Attesto's core SDKs cover direct application integration. Gateway, MCP, OpenTelemetry, and n8n cover the systems around applications: model proxying, agent tools, observability traces, and workflow automation. Each surface must emit real Proofstream evidence, respect source timestamps, and keep secrets out of payloads, receipts, bundles, logs, and browser code.

Scope

This page is for developers and technical operators who integrate Attesto into AI gateways, agent hosts, telemetry pipelines, and automation tools. It does not document internal staff operations and it does not replace the SDK, API, connector, or Local Vault manuals. Use it to choose the correct surface and understand what evidence each one creates.

When to use each surface

Inference Gateway

The Attesto Inference Gateway is a server-side proxy for OpenAI-compatible model calls. Applications send requests to the gateway and change only their base URL. Use it when teams cannot add SDK calls to every application, or when model evidence policy belongs at one controlled boundary.

Production provenance mode has two local services. Local Vault owns capsule signing, encrypted storage, independent mark detection and the durable commitment-envelope queue. The gateway owns only the explicitly allowlisted model connection and, in transform mode, its separated embedding key roles. Generate keys into protected files; key bytes are never command-line values.

attesto-local-vault providers serve-daemons \
  --manifest-dir /opt/attesto/providers \
  --socket /var/lib/attesto/run/providers.sock \
  --auth-key-file /run/secrets/attesto-provider-ipc-key \
  --allowed-uid 10001 \
  --provenance-socket /var/lib/attesto/run/gateway-provenance.sock \
  --provenance-auth-key-file /run/secrets/attesto-gateway-provenance-key \
  --attestomark-detection-private-key-file /run/secrets/attestomark-detection-private \
  --attestomark-embedding-public-key-file /run/secrets/attestomark-embedding-public \
  --provenance-stream-id "$ATTESTO_STREAM_ID"

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --mode provenance-transform \
  --upstream https://api.openai.com \
  --upstream-allow-host api.openai.com \
  --provider-ipc-socket /var/lib/attesto/run/providers.sock \
  --provider-ipc-key-file /run/secrets/attesto-provider-ipc-key \
  --provenance-ipc-socket /var/lib/attesto/run/gateway-provenance.sock \
  --provenance-ipc-key-file /run/secrets/attesto-gateway-provenance-key \
  --attestomark-embedding-private-key-file /run/secrets/attestomark-embedding-private \
  --attestomark-detection-public-key-file /etc/attesto/attestomark-detection-public.hex

export OPENAI_BASE_URL=http://127.0.0.1:8765/v1

curl -sS "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer ${PROVIDER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"Summarize this policy"}]}'

• Local boundary: prompt, completion, model, upstream host, path, usage, finish reason, provider request id, status and latency never leave provenance mode as plaintext. Local Vault encrypts recovery state and submits only randomized commitment roots.
• Measured provider: the gateway must hold a live authenticated Class D lease for its exact binary digest, version, operating-system UID and upstream allowlist. Missing or stale registration rejects inference before the upstream call.
• Streaming: observe SSE is byte-exact. Transform forwards first content immediately, preserves framing/control events, and holds only the bounded mark delta and terminal tail until Local Vault has durably journaled, finalized and queued the capsule.
• AttestoMark Text: eligible text uses the versioned keyed scheme attesto.text.v1.x25519-aesgcm-ed25519-vs16. Short output remains unchanged with not_embedded_too_short; malformed, cancelled, over-limit, or multi-output streams can never claim completed embedding.
• Key separation: the gateway receives embedding-private and detection-public roles. Local Vault receives detection-private and embedding-public roles. Neither side receives the other's private role, and these keys are distinct from IPC, capsule, queue, and signing keys.
• Idempotency and recovery: every call gets a randomized source reference. Exact durable replay returns the same capsule result; changed evidence under one reference is rejected. Platform outage is handled by the Local Vault finalized-envelope queue without reprocessing content.
• Header redaction: Authorization, Proxy-Authorization, Cookie, Set-Cookie, api-key, x-api-key, and headers matching token|secret|key never appear in events, logs, spool entries, or error messages.
• Routing and TLS: the custom dialer ignores environment proxies, denies redirects, validates HTTPS certificates, and resolves only exact hosts listed with --upstream-allow-host.
• Operations: monitor /healthz and /metrics on the separate admin listener. A provenance health failure is fail-closed and never falls back to legacy submission.

MCP server

The Attesto MCP server exposes a narrow set of deterministic Attesto tools to MCP-compatible agent hosts. The current tool surface is log_action, get_receipt, verify_receipt, get_stream_head, and verify_completeness. It logs actions, fetches receipts, verifies receipts offline, inspects stream heads, and proves a sequence range is gap-free without giving the agent broad backend credentials. The MCP server should run server-side in the agent runtime environment. It contains no AI model, no AI-vendor imports, and no hidden decision logic; it is a deterministic tool wrapper over the Attesto SDK.

pip install attesto-mcp

{
  "mcpServers": {
    "attesto": {
      "command": "attesto-mcp",
      "args": ["--stdio"],
      "env": {
        "ATTESTO_BASE_URL": "https://verify.attesto.eu",
        "ATTESTO_API_KEY": "${ATTESTO_API_KEY}",
        "ATTESTO_STREAM_ID": "${ATTESTO_STREAM_ID}"
      }
    }
  }
}

attesto-mcp --stdio

• Store MCP credentials in the agent runtime secret store.
• Do not pass tenant API keys, provider API keys, or raw customer secrets through MCP tool arguments.
• Local verification: verify_receipt and verify_completeness run locally; the trust anchor is the pinned witness public key, not an Attesto backend response.
• Leak guard: payloads are refused when they contain the value of an environment variable ending in _KEY, _TOKEN, _SECRET, or _PASSWORD.
• Keep tool outputs deterministic and receipt-oriented so agent logs can be verified later.
• The package default base URL is intentionally overrideable; set ATTESTO_BASE_URL=https://verify.attesto.eu explicitly for the public Attesto service.
• Restrict available tools per agent role; not every agent needs bundle export or stream creation.

OpenTelemetry bridge

The OpenTelemetry bridge turns selected spans into Attesto events. It is useful when the source of truth is already a trace pipeline: model gateway spans, policy evaluation spans, connector sync spans, or incident handling spans. The bridge must filter aggressively; do not send every span by default.

pip install attesto opentelemetry-sdk

import os
from attesto import AttestoClient
from attesto.otel import AttestoSpanProcessor
from opentelemetry.sdk.trace import TracerProvider

provider = TracerProvider()
provider.add_span_processor(
    AttestoSpanProcessor(
        client=AttestoClient(api_key=os.environ["ATTESTO_API_KEY"]),
        stream_id=os.environ["ATTESTO_STREAM_ID"],
    )
)

• Event type: every ended span becomes one attesto.otel_span commitment event.
• Source reference: spans use deterministic otel:{trace_id}:{span_id} source references, so resending the same span is idempotent.
• Payload discipline: redact attributes that may contain secrets or personal data before the processor sees them; Python uses attribute_allowlist and TypeScript uses attributeAllowlist.
• Commitment-only attributes: only allowlisted attributes are committed, as attributes_commitment plus attribute_keys; non-allowlisted values are not written to Attesto. Disable attribute commitments entirely with commit_attributes=False or commitAttributes: false.
• Host safety: processor failures do not break the host app by default; use strict=True or strict: true when evidence capture failure must fail the request, and use on_error/onError for observability.
• Sampling: align OTel sampling with evidence policy; sampled-away spans cannot become evidence later.
• Verification: receipt IDs should be written back to logs or trace attributes when possible.

n8n node

The Attesto n8n node is for workflow automation that needs verifiable step evidence. Use it for approval workflows, connector handoffs, incident triage, policy checks, and customer-facing automation where a later auditor must see what happened and when.

npm install n8n-nodes-attesto

• Store Attesto credentials in n8n credentials, not workflow JSON.
• Use the action node for Log Event, Log Typed Compliance Event, Get Receipt, and Verify Receipt (Offline).
• Offline receipt verification: Verify Receipt recomputes the canonical hash and Ed25519 signature locally against the witness key pinned in the n8n credential; Attesto servers are not consulted.
• Webhook trigger: use the trigger node only for signature-verified Attesto webhooks. It verifies HMAC over timestamp.body with constant-time comparison and 300 s clock-skew tolerance; stale or forged deliveries receive 401 and do not start workflows.
• Set source object id and source timestamp explicitly for external systems.
• Do not publish workflows with embedded tenant keys, provider tokens, or raw regulated payloads.

Evidence model

All four surfaces should emit evidence through the same Proofstream semantics as the SDKs. A gateway request, MCP tool call, OTel span, or n8n workflow step is not special: it is a source event with a source reference, timestamp, normalized commitment, receipt, and optional downstream window/checkpoint/witness/anchor inclusion.

Security boundaries

• Run Gateway and MCP server-side only; never place Attesto API keys in browser bundles.
• Keep upstream provider secrets in the owning runtime secret store.
• Prefer Local Vault when connector or edge credentials must remain customer-side.
• Mask prompts, responses, trace attributes, and workflow variables when they contain personal data or secrets.
• Use tenant-scoped API keys and revoke them when a gateway, agent host, telemetry collector, or workflow is retired.

Operations

Treat these surfaces as production integrations. They need health checks, retry policy, rate-limit handling, idempotency, source-time validation, and observable failure states. A surface may be installed from a package registry, but it is not production-ready for a tenant until it has a real Attesto API key, a real stream, and a successful receipt/verify canary.

Failure modes

Rollout checklist

• Choose one surface and one production stream; do not enable all surfaces at once.
• Store credentials only in server-side secret stores or n8n credentials.
• Run one real event → receipt → verify canary before inviting users.
• Document source timestamps, source references, and retention policy.
• Add dashboards or alerts for receipt failures, retry conflicts, and secret-scan rejections.
• Update tenant docs and changelog when enabling a new surface.