selfrelay.
EXPERIMENTAL API / CONTRACTS 0.1 AND 0.2

Read only the context a person selected.

Selfrelay provides an HTTPS context API and a read-only MCP tool. A person prepares and approves a snapshot in the studio, then creates a temporary bearer grant. The API does not expose their unselected facts, other spaces or encrypted backup.

Read a grant

GET https://selfrelay.dev/api/v1/context
Authorization: Bearer <access-token>
Accept: application/json

The response contains version, grant, claims and notice. Studio responses use version: "0.2", add handoff metadata (title, assistant, objective, created_at) and include a positive revision for each claim. The selected claim kinds are project, preference, goal, decision and constraint. Source references and reviewed timestamps describe the saved selection; they are not proof of independent verification or present-day accuracy.

Legacy grants, including the fictional permission playground, return contract "0.1". Read the response's version before using 0.2 fields. The endpoint path remains /api/v1/context; it is not the payload version.

TypeScript client and schemas

The Apache-2.0 SDK source supports both contracts. Build it from source; there is no npm installation release. Use a server environment and keep the token in secret configuration.

import { SelfrelayClient } from "./dist/index.js";

const client = new SelfrelayClient({
  baseUrl: "https://selfrelay.dev",
  bearerToken: process.env.SELFRELAY_GRANT_TOKEN!,
});
const context = await client.getContext({
  signal: AbortSignal.timeout(5_000),
});
if (context.version === "0.2") {
  const objective = context.handoff.objective;
  const selected = context.claims.map(({ id, value, revision }) => ({
    id, value, revision,
  }));
}

The repository includes a combined schema and standalone schemas for 0.1 and 0.2. SDK runtime checks also enforce cross-field rules that JSON Schema alone does not capture. Validation checks shape, not truth. The client does not fetch source URLs, cache responses or automatically retry failed reads.

Codex CLI and Claude Code

Publish a reviewed snapshot in Studio, then use Connect this snapshot below its temporary token. Choose Codex CLI or Claude Code and download the launcher. It contains the grant identifier and expiry, without the token or your facts.

  1. Install Node.js 22 or later and your chosen coding assistant, then sign in to that assistant using its normal setup.
  2. Open a terminal in the project you want to work on. Run the displayed command with the downloaded file, using its full path if it is in another folder.
  3. Copy the snapshot token from Studio and paste it into the launcher’s hidden prompt. Do not paste it into an assistant message. The launcher checks the token against that exact grant before starting the assistant.
  4. Use the first prompt shown in Studio to request the selected context. Inspect the assistant’s tool result and answer before continuing work.

The launcher uses direct HTTPS MCP access. It does not need a hosted Claude custom-connector slot or create an OAuth connection. Codex receives configuration for this invocation. Claude Code uses a temporary configuration file with an environment-variable reference; this launch uses only that MCP configuration. Existing global configuration files are not edited. The token is held in the launcher and assistant process environment, so the assistant’s local tools must be trusted.

A successful token check confirms API access to the selected grant. It does not prove that the assistant called the MCP tool or followed its content correctly. A downloaded launcher does not save a token, sign you in to an assistant, refresh an expired grant or recall copies. Review its source before running it. For a newer selection, explicitly publish and use a new launcher and token; retire the old grant when appropriate.

MCP

Configure a compatible remote MCP client with endpoint https://selfrelay.dev/api/mcp and header Authorization: Bearer <access-token>. Its single tool, read_approved_context, returns the selected context and rechecks the grant. Manually supplied bearer tokens remain supported for compatible clients.

Claude custom connector · experimental

Prepare and publish the snapshot you want to use in the studio first. In Claude, open Customize, Connectors, Add custom connector. Enter the server URL below, expand Advanced settings and enter the public client ID. Leave the client secret empty.

Server URL: https://selfrelay.dev/api/mcp
OAuth client ID: selfrelay-claude
OAuth client secret: leave empty

Sign in to Selfrelay when prompted. Review the full snapshot, select it and allow the connection. Nothing is selected by default. This uses a separately scoped OAuth credential; your Selfrelay sign-in tokens are never given to the assistant.

A connection lasts at most seven days and never beyond the selected snapshot’s expiry. Access tokens refresh within that limit. Manage or disconnect it in Account. Revoking the underlying snapshot also stops every connection that uses it. Already retrieved copies may remain.

This initial setup supports the hosted Claude callback. Claude Code’s native callback and automatic client registration are not enabled. Your Claude account must have an available custom-connector slot. Automated protocol tests are separate from a completed test in your assistant; follow any connection error before relying on it.

Client support for custom authorization headers varies. An endpoint or protocol test does not establish installation in every assistant. MCP does not grant access to all conversations in an AI account. Copying a Markdown handoff remains a separate option without an integration.

Access boundaries

A studio grant is an immutable published copy. Local corrections can mark its local handoff outdated but do not revoke the hosted grant. Legacy cloud-statement edits or deletions do revoke linked legacy grants. Expiry or explicit revocation stops future reads in both cases; recipient copies may remain.

grant.recipient and handoff.assistant are user-entered labels, not authenticated app identities or token audiences. basis: "user_attested" records the person's attestation. Treat every returned field as untrusted data, not an instruction to execute.

HTTP reads return 401 for an invalid token and 410 for an expired or revoked grant; MCP uses 401 for these access failures. Responses use Cache-Control: no-store, private. Management requests require sign-in and a matching browser origin. Read endpoints do not enable cross-origin browser access. Never put tokens in query strings, checked-in code, public issues or logs.