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:
| Surface | Protocol | Auth |
|---|---|---|
| Hosted Streamable-HTTP MCP | MCP over HTTP | OAuth 2.1 (including device flow) |
| REST memory routes | REST | API key or OAuth |
| Guard review route | REST | API key or OAuth |
| OpenAI-compatible v1 | REST | API 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-harnessThis writes:
AGENTS.mdsnippet (or.cursor/rulesfor Cursor)- 7-skill pack (skill files)
.mcp.jsonzephr 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 pathAll 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
| Failure | Recovery |
|---|---|
| 401 Unauthorized | Re-authenticate with zephr login |
| Unknown platform in emit | zephr hosts emit --list to see valid ids |
| MCP HTTP endpoint unreachable | Check network; the endpoint is hosted on the Zephr cloud |
| Scope violation on HTTP | Re-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.
Related references
- Universal integration spec — full requirements and scenarios
- Surfaces — CLI and MCP server
- Extensions — extension host packs
- Configure your client — current client configuration