# Ghostclip.dev
> Ephemeral encrypted clipboard service with REST API and MCP server for AI agents.

Ghostclip.dev lets you securely transfer text between any device or environment — no account, no tracking, no data trail. Content is AES-256 encrypted using your access code as the passphrase. Everything expires automatically.

## API (requires Bearer token — get a key at https://ghostclip.dev/mcp)

### REST API
- POST   /api/v1/clipboard              Create a clipboard. Body: {content, ttl_minutes, max_views}. Returns {code, url, expires_at}
- GET    /api/v1/clipboard/<code>       Read clipboard content. Returns {content, expires_at, views_remaining}
- PUT    /api/v1/clipboard/<code>       Update content. Body: {content}
- DELETE /api/v1/clipboard/<code>       Delete clipboard immediately
- GET    /api/v1/words                  Generate a random access code

### MCP Server (Streamable HTTP transport, spec 2024-11-05)
- POST /api/mcp  — JSON-RPC 2.0 endpoint
- Tools: create_clipboard, read_clipboard, update_clipboard, delete_clipboard, generate_code
- Config: {"url": "https://ghostclip.dev/api/mcp", "headers": {"Authorization": "Bearer <api_key>"}}

## Pages
- /          Main clipboard interface (no login required)
- /docs      REST API reference with code examples (curl, Python, JS)
- /about     Full documentation in EN, ES, IT, FR, DE
- /mcpinfo   REST API and MCP integration guide with copy-paste configs
- /mcp       API key management (generate/revoke keys)
- /legal     Legal notice and privacy policy

## Key facts
- No registration or account required for web use
- Zero-knowledge: server stores only SHA-256 hash of the code, never the code itself
- TTL: 5 minutes to 24 hours (configurable per clipboard)
- Max size: 128 KB per clipboard
- Rate limit: 100 API calls per key per 24 h; headers: X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After

## Use cases

**Pass data between agents or sessions**
Create a clipboard with context, a summary, or intermediate results from one session.
Share the code so another agent or a later session can read it.
Recommended: ttl_minutes=60, max_views=1.

**Ephemeral scratchpad during long tasks**
Store intermediate results (search output, parsed data, draft text) in a clipboard
instead of keeping everything in the context window. Update it as work progresses.
Delete when the task is complete.

**Secure one-time secret delivery**
Create a clipboard with max_views=1 and ttl_minutes=10.
After one read the content is permanently and irrecoverably deleted.
Useful for temporary tokens, one-time passwords, or sensitive strings.

**Agent-to-human handoff**
Write a report, summary, or generated file to a clipboard.
Give the user the URL https://ghostclip.dev/<code> to retrieve it from any browser.
No account or installation required on their end.

**Coordinate parallel agents**
Use generate_code to pre-negotiate a shared code before spawning sub-agents.
Agent A writes results; Agent B reads them. Update content to signal state changes.
Both agents use the same code; no side channel needed.

**Transfer text to a device without a working clipboard**
Write content to a clipboard; give the user a 3–4 word code to type at ghostclip.dev
on a VDI session, remote server console (IPMI/iDRAC), game console, smart TV, or
any browser where copy-paste is unavailable or disabled by policy.

## Workflow patterns

1. create → share code → read (one-time delivery, use max_views=1)
2. generate_code → share code out-of-band → create → read (pre-negotiated rendezvous)
3. create → update (repeatedly) → delete (shared mutable scratchpad)
4. create with max_views=1, ttl_minutes=5 → share URL → auto-deletes after first read

## Limits and constraints
- Content max 128 KB (~100,000 words). Plain text only; not suitable for binary data.
- Valid TTL values (minutes): 5, 10, 15, 30, 60, 90, 120, 720, 1440.
- Codes are 3 or 4 lowercase words (letters a-z, digits 0-9). Example: "apple mango7 grape".
- If the code is lost, data is unrecoverable. No master password, no recovery option.
- Not intended for PII, production credentials, or sensitive long-lived data.
- The server does not make backups. Data loss on expiry is by design.

## Error handling
- 401 Invalid or missing API key  → check Authorization: Bearer <key> header
- 404 Clipboard not found         → expired, deleted, or wrong code
- 410 Gone                        → max_views reached; clipboard was auto-deleted after that read
- 429 Rate limit exceeded         → wait Retry-After seconds before retrying
- 503 Service unavailable         → retry with exponential backoff (start at 1 s)