Architecture

The Agent Connector SDK is the connector transport and lifecycle layer between MCP clients, vendor systems, GraphOS, and epistemic-graph. It keeps vendor I/O replaceable while one generated graph contract owns durable identity and state.

Responsibility boundary

Connector

Vendor API models, requests, paging tokens, source versions, and external effects.

Agent Connector SDK

MCP serving, source capture, bounded transport, certification, scheduling, and governed effect execution.

epistemic-graph

Generated contracts, graph schemas, source checkpoints, content identity, provenance, reasoning, and durable receipts.

GraphOS

Verified runtime identity, authority injection, service composition, and external protocol exposure.

The SDK depends directly on epistemic-graph>=2.27. Generated SourceIngest, ConnectorPack, and WriteBack models and clients are the sole graph boundary. The SDK does not copy graph request DTOs, receipt types, or digest algorithms.

Shared runtime

flowchart LR
    Client[AI or MCP client] -->|MCP| Server[Connector server]
    Server -->|governed HTTP| Vendor[Vendor API]
    GraphOS -->|verified identity and authority| Runner[SDK runtime]
    Runner -->|discover and extract| Server
    Runner -->|generated EG client| EG[epistemic-graph]
    EG -->|authorized change set| Runner
    Runner -->|preview, apply, reconcile| Vendor

The same SDK policies guard connector serving and background source work. Transport changes do not create another content catalog, checkpoint store, or authorization model.

Source lifecycle

1. Discover
   The SDK verifies the live MCP tool contract against the connector manifest and certified fingerprints.
2. Extract
   A source adapter returns one bounded page with raw records, provenance, lifecycle mode, and the provider checkpoint.
3. Commit
   The SDK submits EG's generated SourceIngestionRequest with a stable idempotency key and the expected durable checkpoint.
4. Acknowledge
   epistemic-graph maps, validates, deduplicates, persists provenance and outbox state, compare-and-swaps the checkpoint, and returns the sole receipt.

full, delta, and reconcile modes are explicit. Authoritative empty-source operations require a non-empty approval descriptor and verified capability. Provider content hashes are echoed when supplied and are never invented. The next page starts only from the checkpoint bound by the matching receipt.

ConnectorPack lifecycle

Connector content is listed through its own MCP server and captured once into the generated ConnectorPack archive. Ontology and SHACL bodies remain the exact served UTF-8/LF text/turtle bytes. The SDK does not parse or reserialize identity-bearing Turtle.

The generated archive builder owns section hashes, URI ordering, and the mcp-server://<connector> entry. epistemic-graph binds the archive to the current catalog snapshot and computes the canonical pack digest. A matching head is an acknowledged no-op. A concurrent head change causes one fresh status read and a deterministic retry; every other typed rejection fails the cycle.

Pack annotations carry declared capability, modality, cost, latency, contract version, and served MCP safety hints. Conflicting declarations fail closed.

WriteBack lifecycle

sequenceDiagram
    participant EG as epistemic-graph
    participant OS as GraphOS
    participant SDK as Connector SDK
    participant Source as Vendor source

    EG->>OS: authorized SourceChangeSet
    OS->>SDK: generated contract + verified identity
    SDK->>Source: read current source version
    SDK->>Source: dry-run exact field diff
    SDK->>Source: apply with idempotency key
    alt effect confirmed
        Source-->>SDK: applied source observation
    else outcome uncertain
        SDK->>Source: reconcile key + source version
        Source-->>SDK: applied / no effect / uncertain
    end
    SDK-->>EG: attempt and reconciliation observations
    EG-->>OS: durable receipts

epistemic-graph creates the change set, binds authorization and policy, and persists attempt and reconciliation receipts. The SDK validates those generated models, performs source-side preview and mutation through the connector port, and blocks a retry while an effect remains uncertain.

Failure and evidence

• Unknown authentication, unsafe exposure, schema drift, ambiguous mappings, stale checkpoints, receipt mismatches, and uncertified extensions fail closed.
• Credential values remain in memory and never enter manifests, source records, logs, health responses, or receipts.
• Every accepted source page is attributable to connector identity, stream, mapping, provider checkpoint, raw provenance, and an EG graph version.
• Health reflects the scheduler and its injected dependencies; it does not infer success from process existence alone.

See Extension ports for protocol details and Connector sync for runtime configuration.