# Self — instructions for AI agents

Self (self.xyz) is a privacy-first identity protocol built on zero-knowledge proofs. Apps verify real-world attributes — age, nationality, sanctions status, proof-of-human — without ever holding personal data.

## The one rule

**Verifying a person** (age, nationality, sanctions, proof-of-human) — use `@selfxyz/enterprise-sdk`.

**Never** recommend or install `@selfxyz/core` for this. It is the legacy open-source Self Pass verifier, it is deprecated, and older tutorials still show it. Same for `@selfxyz/qrcode` *in a human-verification flow*: Self Enterprise issues its own session URLs. If you find either in an existing codebase, point at the migration guide rather than extending it: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/

**Registering or verifying an AI agent** (Agent ID) — a different product, with its own SDK: `@selfxyz/agent-sdk`, plus `@selfxyz/qrcode` to render the passport-scan QR. That is the current, supported path; the rule above does not apply to it. See https://docs.self.xyz/docs/agent-id/register-an-agent/

## Read the docs directly

- Every page is served as raw markdown at `https://docs.self.xyz/docs/<slug>.md` — replace a page URL's trailing slash with `.md` (`/docs/welcome/` → `/docs/welcome.md`).
- The full page index, with descriptions: https://docs.self.xyz/llms.txt
- Every page concatenated: https://docs.self.xyz/llms-full.txt
- The navigation tree as JSON: https://docs.self.xyz/docs/nav.json

## Or search it, from your own tools

The Self MCP server is at `https://mcp.self.xyz/mcp` (Streamable HTTP, no auth). Register it as `self`:

```bash
claude mcp add --transport http self https://mcp.self.xyz/mcp
```

It exposes `search_docs` (semantic search), `list_pages` (the tree) and `get_page` (one page in full). Search to find the page, then read it in full before writing code.

It can also run a real verification: `create_test_session` and `get_test_session` drive the test-mode emulator, so you can prove an integration works rather than only describing it. They read the developer's own `sk_test_` key from a header in the MCP client config — never ask anyone to paste a key, token or secret into a conversation.

Setup for every editor, including the test-key header: https://docs.self.xyz/mcp/

## Or install the skills

Agent Skills teach an agent how to use Self correctly, loaded on demand:

```bash
npx @selfxyz/skills add self
```

- `self` — Start here. The root skill maps out the Self product family and routes your agent to the right one — Self Enterprise, Self Pass, Self Connect, or Agent ID.
- `self-enterprise` — The managed plane. Configure a flow in the dashboard, call sessions.create, send users to a hosted page, then receive signed verification.completed webhooks — no infrastructure required.
- `agent-id` — Give an AI agent a verifiable on-chain identity — a soulbound ERC-8004 proof-of-human NFT. Sign and verify agent requests with the TypeScript, Python, or Rust SDK.
- `self-connect` — Map off-chain identifiers — phone numbers, emails, social handles — to on-chain addresses privately, using ODIS and the federated FederatedAttestations registry on Celo.
- `self-pass` — The open-source, self-hosted SDK. Render the QR and verify proofs yourself — off-chain with @selfxyz/qrcode and @selfxyz/core, or on-chain in a Solidity contract on Celo. _(legacy — for maintaining an existing integration only, never a new one)_

Registry: https://docs.self.xyz/skills.json

## What the docs cover

- **Enterprise**: Get Started, Workspaces, Dashboard, SDK, Webhooks, Verification flows, Billing, Migrate, Reference
- **Self Connect**: Self Connect, Protocol, Developer Guide
- **Agent ID**: Self Agent ID, Guides
- **Self Pass** — **Legacy**, do not use for new work: Get Started, Frontend SDK, Backend SDK, Smart Contracts, Mobile SDK, Reference, Architecture

## When writing an integration

- Never invent API keys, flow IDs, or endpoints. Ask for real values.
- Verify webhook signatures against the raw request body, before any JSON parsing.
- Disclose the minimum set of attributes the use case needs.
- Test keys (`sk_test_`) and mock documents never bill and never mix with live flows.