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; the gateway forwards to the configured upstream provider and writes Attesto evidence before returning the provider response. Use it when teams cannot add SDK calls to every application, or when central policy and model routing are required.

export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"
export OPENAI_BASE_URL=http://127.0.0.1:8765/v1

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --attesto-base-url https://verify.attesto.eu \
  --upstream https://api.openai.com/v1 \
  --stream-id "$ATTESTO_STREAM_ID" \
  --capture commitments

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"}]}'

• Capture mode: commit request and response metadata, not raw secrets or provider credentials.
• Allowed modes: commitments and none are the only capture modes; raw prompt/response capture deliberately does not exist.
• OpenAI-compatible paths: /v1/chat/completions, /v1/completions, /v1/embeddings, and /v1/responses create attesto.model_decision events. Other paths are proxied untouched and attested as generic http_call commitment events.
• Streaming: SSE responses pass through byte-for-byte with immediate flushing; the gateway reassembles the stream after completion only to compute commitments.
• Source time: preserve the caller timestamp where supplied; otherwise record gateway receive time with timezone.
• Idempotency: use a request id or source reference so retries do not create conflicting history.
• Delivery: events use a bounded queue and background batches. Attesto outages or queue overflow go to a fsynced NDJSON dead-letter spool, replayed automatically or with attesto-gateway replay-spool. --spool-max-bytes is the only drop point and is counted and logged loudly.
• 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.
• Fail behavior: the gateway fails open by default with warnings and fsynced spool; add --strict when policy requires receipt creation before upstream work continues.
• Routing and TLS: keep upstream TLS verification enabled and use explicit --route entries for multi-upstream deployments.
• Operations: monitor /healthz and /metrics on --admin-listen, and use attesto-gateway replay-spool after outages.

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.