# Integration profiles

**Proposed architecture.** A website, API, MCP connection or software library is a way to access an implementation. Its presence does not establish the security of the checks behind it. The options below do not announce available products, supported endpoints, protocol conformance or production readiness.

## One verification core, different interfaces

The proposed architecture uses one deterministic verification core: the same evidence, authenticated trust and status inputs, recipient policy and checking time should produce the same technical result. Interfaces would collect inputs and present that result without changing its meaning. Network retrieval, authentication and storage need their own controls around the core.

- **Website**: Intended role: Let a person submit evidence and inspect checks. Boundary to make explicit: Whether processing occurs locally or on a server; operator, retention and supported checks.
- **Hosted API**: Intended role: Integrate checks into an institution's workflow. Boundary to make explicit: Authenticated caller, recipient context, tenant separation and result scope.
- **MCP tool**: Intended role: Make supported checks available to an agent workflow. Boundary to make explicit: Tool authorisation, evidence treated as data, and preservation of the underlying result.
- **SDK or CLI**: Intended role: Run checks within the recipient's environment. Boundary to make explicit: Versioned dependencies, local policy, update responsibility and access to current trust and status information.

This common core is a design direction. It is not an assertion that existing demonstrations share an implementation. Each release would need evidence that its interfaces preserve the same checks and outcomes. See [Verifier behaviour](verifier-behaviour.md).

## Agent and MCP boundaries

An agent may request a permitted check and explain the result. It must not turn unavailable evidence into a pass or substitute its own conclusion for the recorded technical result. Instructions found inside a document are document content, not authority to change the recipient's policy or invoke tools.

A proposed verification tool should expose only its stated operations under scoped authorisation. It should not expose a general signing command, key management, trust-list changes or issuance approval. Private keys, recovery material and service credentials do not belong in prompts or tool arguments. The tool's authenticated connection and the issuer's signing authority are separate mechanisms.

For agent-assisted issuance, exact-content approval and signing controls remain outside the model. Adding MCP does not replace a custody arrangement or issuer authorisation. See [Issuer and key security](issuer-and-key-security.md).

An authenticated remote MCP integration needs resource-bound tokens, explicit tool permissions and separation between tenants and downstream services. The [MCP authorization specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/basic/authorization.mdx) requires the server to validate that an access token is intended for it; forwarding that token unchanged to another service is not an acceptable substitute for that service's own authorisation. Select and test a protocol version before advertising support.

Interfaces also need bounded uploads, parsing and network retrieval, controlled destinations for referenced resources, request limits and sanitised results. A document-supplied URL is not permission to fetch an arbitrary resource. Logs and error messages should identify the check and its outcome without copying credentials, hidden claims or access secrets. These are design requirements, not claims about deployed safeguards.

## Protocol choices

The [SD-JWT VC binding](../shared/sd-jwt-vc-binding.md) pins the credential format and draft versions. Issuance and presentation protocols add separate requirements. OpenID4VCI, OpenID4VP or a high-assurance profile should be named as supported only for a specific implementation, version, scope and demonstrated conformance. A format example or result-checker test does not establish interoperability.

In [OpenID4VCI 1.0, section 4.1.1](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-4.1.1), a pre-authorized code is short-lived and single-use; `tx_code` is optional. [Section 14.3](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-14.3) permits multiple credential requests with the same access token, subject to the issuer's policy. These are different from re-reading an offer or authorising a particular signing operation. Any stricter Realworld rule would need a named, approved profile with explicit retry and batch behaviour; it is not a universal protocol requirement.

Before an integration is offered, its documentation should identify the operator, processing location, retained information, supported checks, protocol versions and response to unavailable dependencies. Local operation and selective disclosure do not, by themselves, establish privacy or current status. Publication and release claims are governed separately by [Assurance and release](assurance-and-release.md).
