Agent docs

Use Floppy from an agent host.

Floppy gives agents a small, tenant-bound surface for searching memory, reading sourced articles, building meeting context, and submitting review-required drafts.

Start with search Product overview Open in-app setup

Inside Floppy

Use the app to issue the token; use this page to wire the host.

Create and revoke personal agent tokens from Use Floppy in other tools. That same in-app page has the tenant endpoint, host recipes, and a draft review link for the first smoke test.

Quickstart

Use placeholders until your tenant token is issued.

Environment

export FLOPPY_AGENT_ENDPOINT="https://hellofloppy.com/api/v1/agent"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
export FLOPPY_AGENT_WIKI_QUERY="Floppy"
npm run smoke:agent-onboarding

Search memory

curl "$FLOPPY_AGENT_ENDPOINT/v1/wiki/search?q=current%20priorities" \
  -H "Authorization: Bearer $FLOPPY_AGENT_TOKEN"

Submit a draft

curl -X POST "$FLOPPY_AGENT_ENDPOINT/v1/drafts/submit" \
  -H "Authorization: Bearer $FLOPPY_AGENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "type": "email_recap",
    "target_kind": "entity",
    "target_entity_id": "entity_client_example",
    "subject": "Project update draft",
    "body": "...",
    "citations": [{"assertion_id": "assertion_..."}]
  }'

Host recipes

Use OAuth for Cowork, or bearer tokens for CLI hosts.

Cowork/Desktop

# Cowork setup
Personal Claude account: add Floppy from Claude's custom connector settings, then sign in when Claude prompts you.
Claude Team or Enterprise: a Claude organization owner must add Floppy once before individual users can connect.

Connector name: Floppy
Connector URL: https://<your-floppy-mcp-endpoint>/mcp
Authentication: OAuth

After connecting, ask Claude in Cowork/Desktop to call `floppy_setup_check`.
Do not paste personal login credentials or bearer tokens into Cowork.

# Run it
Open the Floppy plugin in Cowork/Desktop.
Ask it to search Floppy memory for the current task, read cited context, or submit a review-required draft.
Supported hosts capture each session turn back to Floppy as source evidence.
Submit only review-required drafts; do not send or create external actions directly.

Claude Code

# Shell
export FLOPPY_AGENT_ENDPOINT="https://hellofloppy.com/api/v1/agent"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
curl "$FLOPPY_AGENT_ENDPOINT/v1/wiki/search?q=<topic>" \
  -H "Authorization: Bearer $FLOPPY_AGENT_TOKEN"

# CLAUDE.md
When the user asks for company memory, search Floppy first.
Use FLOPPY_AGENT_ENDPOINT and FLOPPY_AGENT_TOKEN from the environment.
The token is a personal Floppy agent token; never print it or commit it.
Search first. If an entity id is known, read /v1/profiles/:entityId/context?q=<task>; otherwise read the best article before answering.
Cite evidence ids and say when Floppy does not know.
Submit only review-required drafts to /v1/drafts/submit.

# Import session
export FLOPPY_AGENT_ENDPOINT="https://hellofloppy.com/api/v1/agent"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
npm run import:coding-agent-session -- \
  --file ./path/to/claude-code-session.jsonl \
  --format claude-code \
  --redaction basic \
  --review \
  --idempotency-key <stable-session-id>
npm run import:coding-agent-session -- \
  --file ./path/to/claude-code-session.jsonl \
  --format claude-code \
  --redaction basic \
  --idempotency-key <stable-session-id>

Codex

# Shell
export FLOPPY_AGENT_ENDPOINT="https://hellofloppy.com/api/v1/agent"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
curl "$FLOPPY_AGENT_ENDPOINT/v1/wiki/articles" \
  -H "Authorization: Bearer $FLOPPY_AGENT_TOKEN"

# AGENTS.md
Use Floppy for tenant memory questions.
Read FLOPPY_AGENT_ENDPOINT and the personal FLOPPY_AGENT_TOKEN from the environment; never echo the token.
Search /v1/wiki/search. If the prompt includes an entity id, read /v1/profiles/:entityId/context?q=<task>; otherwise read /v1/wiki/articles/:slug.
Cite assertionIds or sourceArtifactIds and refuse unsupported claims.
Do not write directly to external tools; submit review-required drafts only.

# Import session
export FLOPPY_AGENT_ENDPOINT="https://hellofloppy.com/api/v1/agent"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
npm run import:coding-agent-session -- \
  --file ./path/to/codex-session.jsonl \
  --format codex \
  --redaction basic \
  --review \
  --idempotency-key <stable-session-id>
npm run import:coding-agent-session -- \
  --file ./path/to/codex-session.jsonl \
  --format codex \
  --redaction basic \
  --idempotency-key <stable-session-id>

HTTP client

# curl
export FLOPPY_AGENT_ENDPOINT="https://hellofloppy.com/api/v1/agent"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
curl "$FLOPPY_AGENT_ENDPOINT/v1/profiles/<entity-id>/context?q=<topic>" \
  -H "Authorization: Bearer $FLOPPY_AGENT_TOKEN" \
  -H "accept: application/json"

# fetch
const response = await fetch(
  `${process.env.FLOPPY_AGENT_ENDPOINT}/v1/wiki/search?q=${encodeURIComponent(topic)}`,
  {
    headers: {
      authorization: `Bearer ${process.env.FLOPPY_AGENT_TOKEN}`,
      accept: "application/json",
    },
  },
);

Native MCP

# Claude Code Terminal command
export FLOPPY_MCP_URL="https://<your-floppy-mcp-endpoint>/mcp"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
claude mcp remove --scope local floppy >/dev/null 2>&1 || true
claude mcp remove --scope project floppy >/dev/null 2>&1 || true
claude mcp remove --scope user floppy >/dev/null 2>&1 || true
claude mcp add --scope user --transport http floppy "$FLOPPY_MCP_URL" \
  --header "Authorization: Bearer $FLOPPY_AGENT_TOKEN"
claude mcp list

After this Terminal command succeeds, open Claude Code and ask it to call `floppy_setup_check`.

# Codex
export FLOPPY_MCP_URL="https://<your-floppy-mcp-endpoint>/mcp"
export FLOPPY_AGENT_TOKEN="<personal-agent-token>"
codex mcp add floppy --url "$FLOPPY_MCP_URL" \
  --bearer-token-env-var FLOPPY_AGENT_TOKEN
codex mcp list

Auth today

Cowork/Desktop signs in through WorkOS OAuth. CLI, local MCP, and HTTP recipes can still use Authorization: Bearer <token> with personal or tenant-managed Floppy tokens.

Security posture

Store tokens in an agent host secret store or local environment. Rotate if a token appears in a shared prompt, repository, or log.

Endpoint contract

Small enough for agents to use reliably.

GET/v1/wiki/articlesList article candidates for a tenant.

GET/v1/wiki/articles/:slugRead one sourced knowledge article.

GET/v1/wiki/search?q=...Search articles, entities, and source artifacts.

GET/v1/profiles/:entityIdRead a profile with facts, freshness, and citations.

GET/v1/profiles/:entityId/context?q=...Read profile-backed answer plans, evidence leads, and supporting search.

POST/v1/source-artifacts/imports/coding-agent-sessionImport an exported coding-agent session as sourced chat evidence.

POST/v1/meetings/:meetingId/contextBuild meeting context for recap drafting.

POST/v1/drafts/submitSubmit a review-required email or task batch draft.

GET/v1/drafts/:draftIdRead back a draft and its approval state.

Usage rules

Make the agent earn the answer.

Search before answering

Use search to find the right article or artifact before giving a user a Floppy-backed answer.

Read before drafting

Use article read for answers that will become recaps, decisions, tasks, or customer-facing text.

Cite evidence ids

Carry assertionIds and sourceArtifactIds forward in answers and draft submissions.

Refuse unsupported claims

If Floppy search has no useful result or article read returns 404, say Floppy does not know.

Submit drafts only

Use /v1/drafts/submit for outbound work. Floppy keeps drafts review-required in v1.

Launch posture

What is still coming

Richer provider-specific setup generators and public SDK packaging are still on the roadmap. The current contract supports direct OAuth MCP for Cowork/Desktop while preserving static bearer-token setup for compatible CLI and automation hosts.