Zephr Docs

Universal integration

Universal integration hosts the declarative source-of-truth schema for host platforms, the CLI emit command, the documented agent-facing HTTP surface, the supported external developer path, and advisory host-hook semantics.

Status

Planned. The spec is complete and reviewed (openspec/specs/universal-agent-integration/spec.md). The implementation is not yet wired: the HTTP surface, host-pack rendering, and external developer path exist as requirements and design artifacts, not as production code.

Core concepts

Declarative integration source of truth

Zephr maintains one declarative integration definition per host platform:

{
  id: 'deepseek-harness',
  displayName: 'DeepSeek Harness',
  summary: 'Host integration pack',
  status: 'shipped',
  surface: 'mcp',
  notes: [],
  skills: [],
  files: [],
  mcp: {},
  auth: {}
}

Host pack files are rendered from this definition, not hand-maintained copies. Two packs cannot contain divergent copies of the same skill text.

CLI emit command

zephr hosts emit <platform>

Writes the platform's pack files (skills, AGENTS/rules snippet, MCP config, manifest) into the target project. Fails with an actionable error for unknown platforms.

Agent-facing HTTP surface

The documented agent-facing integration path is composed of:

SurfaceProtocolAuth
Hosted Streamable-HTTP MCPMCP over HTTPOAuth 2.1 (including device flow)
REST memory routesRESTAPI key or OAuth
Guard review routeRESTAPI key or OAuth
OpenAI-compatible v1RESTAPI key or OAuth

No parallel memory state machine is introduced; all documented paths route through the same kernel as MCP tools.

Supported external developer path

There is a supported path for developers outside this monorepo to integrate a host with Zephr — either a public scope-admission flow for native adapters or a first-class documented MCP-only contract. The docs state which one is official.

Vendoring monorepo-private files is not a supported integration path.

Setup and configuration

Emitting a host pack

# List supported platforms
zephr hosts emit --list

# Emit the DeepSeek Harness pack
zephr hosts emit deepseek-harness

This writes:

  • AGENTS.md snippet (or .cursor/rules for Cursor)
  • 7-skill pack (skill files)
  • .mcp.json zephr server entry

HTTP integration (agent authors)

The shipped Streamable-HTTP MCP endpoint is POST /api/cloud/mcp on the configured Zephr API host. It requires an OAuth bearer token and accepts standard MCP JSON-RPC requests. Interactive authentication uses zephr login; automated clients use separately issued credentials.

Hosted responses announce the server revision via X-Zephr-Server-Version (and legacy alias Mcp-Server-Version). These headers are Zephr-private extensions rather than spec-mandated headers. In strict conformance mode, private headers are omitted so standard compliance test suites pass cleanly.

Data flow

Agent author → HTTP API → Zephr cloud kernel → Postgres (RLS-scoped)
                         ↕
                   Same MCP tool handlers as stdio path

All documented HTTP paths route through the same kernel as MCP tools — there is no parallel memory state machine.

Persistence and security

  • Authentication: OAuth 2.1 with device flow for interactive sessions; API key for automated agents. All documented paths require valid credentials.
  • Unauthenticated requests: fail closed — the API returns 401 and records no memory mutation.
  • Tenant isolation: HTTP requests are scoped to the authenticated installation via the same RLS policies as MCP tools.
  • No cookie auth: the agent-facing HTTP surface uses bearer tokens, never cookie-auth REST routes.

Limits

  • The Streamable-HTTP MCP endpoint and host-pack emit command ship.
  • Native adapter scope admission and a public SDK quickstart remain incomplete.
  • The external developer path spec is complete but no public SDK or quickstart exists.

Failures and recovery

FailureRecovery
401 UnauthorizedRe-authenticate with zephr login
Unknown platform in emitzephr hosts emit --list to see valid ids
MCP HTTP endpoint unreachableCheck network; the endpoint is hosted on the Zephr cloud
Scope violation on HTTPRe-admit the installation; the scope is derived from the token

What is designed but not shipped

Everything in this section is designed. The primary gaps:

  • Quickstart: no runnable examples exist for agent authors.
  • OpenAPI fragments: the spec calls for published OpenAPI covering recall/remember/ review-act flows; none exist yet.
  • Native adapter scope-admission flow: designed as the public integration path but not implemented.