# Fanful developers and agents Fanful exposes developer and agent entry points through MCP, HTTP manifests, markdown mirrors, and public discovery files. The current direction is MCP-first: ChatGPT-specific app metadata and widgets should layer on top of the same tools and resources used by Codex, Claude Code, CLI, and other MCP clients. ## Available now - Human hub: /developers-and-agents - One-agent setup page: /agent-setup - One-agent setup prompt: /agent-setup/prompt.md - Deep developer docs: https://docs.fanful.net - Developer docs markdown: /docs.md - API reference: /api - API reference markdown: /api.md - Agent skills: /skills - Agent skills markdown: /skills.md - Existing agent overview: /agents - Discovery file: /llms.txt - Agent guide: /agent-docs/fanful-agent-surface.md - Agent SDK starter: /agent-docs/fanful-agent-sdk-starter.md - Hosted runtime boundary: /agent-docs/fanful-hosted-agent-runtime.md - Agent-ingestion Q&A matrix: /agent-docs/fanful-agent-ingestion-qa.md - Public MCP endpoint: /mcp - Artist-analytics manifest: /api/agent/artist-analytics - Media-upload session manifest: /api/agent/media-upload-sessions - Workflow-trigger manifest: /api/agent/workflow-triggers - Agent-session manifest: /api/agent/sessions - Sync-job manifest: /api/agent/sync-jobs - Work-log sync feed: /api/agent/sync-feeds/work-log - Local MCP server: npm run mcp:server - Local MCP smoke: npm run mcp:smoke - HTTP MCP smoke: npm run mcp:smoke:http ## Status glossary - Manifest-only: Fanful publishes a model-readable HTTP/MCP manifest so agents can discover the shape, fields, redactions, and future workflow. It is not an executable feature yet. - Contract-only: Fanful has written down the safety contract for an action, including auth, confirmation, audit, idempotency, and redaction rules. The action remains blocked until a narrow confirmed write wrapper ships. - API-only: The server endpoint exists outside the current MCP catalog. Agents can use it only with the documented HTTP contract and required scoped credentials. ## SDK starter examples - TypeScript example: examples/fanful-agent-starter/client.ts in the repo. - Public markdown starter: /agent-docs/fanful-agent-sdk-starter.md - No-SDK fallback: call /llms.txt, /api/agent/* manifests, /api/agent/action-contracts, and /api/agent/action-contracts/envelope over HTTP. - Credentials stay in headers, environment variables, or MCP client config. Do not paste bearer tokens, admin tokens, Stripe ids, checkout URLs, or raw private ids into model-visible prompts. - 401 means unauthenticated; 403 means authenticated but missing scope or role. Stale-state, idempotency, retry, and redaction boundaries are part of the client contract. ## API reference, recipes, and skills - API reference: /api - API markdown: /api.md - Skills page: /skills - Skills markdown: /skills.md - Setup prompt: /agent-setup/prompt.md - Fanful has HTTP agent manifests, MCP, action contracts, workflow-trigger subscriptions, sync feeds, and a repo CLI today. Official language SDK packages such as Python are not published yet; /api documents the release checklist for versioned schemas, auth, webhook helpers, examples, CI, package ownership, and support policy. - Webhook recipes should verify x-fanful-signature on the raw body, dedupe by event/idempotency key, read the linked manifest for current state, then call the external platform. Secrets stay in environment variables or secret stores, never prompt-visible text. ## Hosted runtime boundary - Public markdown boundary: /agent-docs/fanful-hosted-agent-runtime.md - Current recommendation: external-first, with no arbitrary third-party code or general Fanful-hosted worker runtime enabled. - Future Fanful-managed workers need a safe run record with status, logs, correlation id, idempotency key, redacted inputs/outputs, limits, approval state, cancellation, retries, and audit links before implementation. - Workflow triggers notify agents, agent sessions record redacted run history, sync jobs define checkpoints, MCP/API manifests expose current capabilities, and action contracts remain mandatory before any mutating worker calls a Fanful write wrapper. ## Current MCP tools - fanful_agent_surface_list: no-network catalog of current Fanful agent surfaces, safe-use policy, and linked issues. - fanful_agent_manifest_read: fetches one current agent manifest over HTTP. - fanful_agent_action_contracts_read: reads the #608 action-contract manifest, optionally filtered by audience or domain. - fanful_agent_manifest_read with surface=workflow-triggers: reads the #1112 signed webhook trigger catalog for event-driven agents. Live-readiness changes, agent-started support checkouts, visible verified-listener idea submissions, and community moderation changes now expose signed, redacted trigger status. The #1523 subscription registry endpoint can create and manage redacted destinations, and #1531 adds manual signed test deliveries. #1537 adds automatic runtime fan-out for visible `member.idea.submitted` events only; other trigger families stay manual-test-only or manifest-ready until future slices. - fanful_agent_manifest_read with surface=agent-sessions: reads the #1113 external agent run/session contract. Durable session storage and event streaming are planned, not enabled yet. - fanful_agent_manifest_read with surface=sync-jobs: reads the #1114/#1224 cursor-based imported-data sync contract and manual worker status. The first executable worker persists redacted Stripe catalog app-reference drift runs; the first concrete feed is #1176 at /api/agent/sync-feeds/work-log for public work-log upserts after an opaque cursor. Arbitrary hosted provider sync execution is still planned separately. - fanful_sync_job_status_read: reads the latest or addressed durable sync run, checkpoint, stats, and redacted output with scoped creator/admin credentials. - fanful_sync_job_run: runs the first-party Stripe catalog app-reference drift worker with an idempotency key and audit correlation id. It does not accept provider credentials, create Stripe objects, update entitlements, or write catalog state. - fanful_agent_manifest_read with surface=domains: reads the #680/#729/#733/#1780 domain setup contract for Fanful subdomains, BYO-domain DNS, Cloudflare Registrar quote/checkout readiness, and guarded final registration. - fanful_domain_setup_read: focused read for the same domain setup contract. It does not execute payment, DNS provider, checkout, or final registration writes. - fanful_agent_manifest_read with surface=artist-analytics: reads the #1192 creator/admin analytics contract. Guest calls return 401, listener-only calls return 403, and authorized creator/admin callers see source funnels, top content outcomes, listener cohorts, and recent signals while raw listener rows and identifiers stay redacted. - fanful_agent_manifest_read with surface=media-upload-sessions: reads the #1299 creator media upload-session contract. Agents can confirm metadata, provenance, idempotency, and audit intent; raw media/artwork bytes stay in the multipart handoff through agentUploadSessionId. - fanful_creator_analytics_read: focused read for the same artist-analytics contract, with optional window filtering and env-gated/scoped credentials. - fanful_member_idea_board_read: reads visible member ideas, viewer vote state, and authorized admin-redacted review fields. - fanful_member_idea_submit: submits one visible member idea through the shared confirmed-write envelope with scoped listener auth, exact confirmation, idempotency, and audit correlation. - fanful_member_idea_vote_toggle: toggles or sets one listener vote on a visible idea through the same confirmed-write envelope. - fanful_creator_lesson_price_preview: previews lesson or coaching price/policy impact without mutating Fanful, Stripe, checkout, or public pages. - fanful_creator_service_price_policy_update: executes a confirmed lesson price write through the shared envelope with exact confirmation, idempotency, stale-state, reason, audit correlation, and scoped/admin credentials. - fanful_creator_lesson_policy_update: creates or updates one lesson policy settings row through the shared envelope with exact confirmation, idempotency, stale-state, reason, audit correlation, and scoped/admin credentials. It never executes refunds, spends credits, cancels bookings, or mutates Stripe. - fanful_creator_lesson_availability_update: creates or updates one future open/cancelled lesson availability window through the shared envelope with exact confirmation, idempotency, stale-state, reason, audit correlation, and scoped/admin credentials. It preserves meeting URLs and private notes, and never mutates bookings, credits, refunds, Stripe, or held/booked slots. - fanful_creator_lesson_stripe_price_select: selects or clears one already-known lesson Stripe Price mapping through the shared envelope with exact confirmation, stale-state, catalog checks, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_lesson_stripe_price_create: creates and selects one replacement lesson Stripe Price through the server route with exact confirmation, server-side Stripe credentials, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_membership_stripe_price_select: selects or clears one already-known membership tier Stripe Price mapping through the shared envelope with exact confirmation, stale-state, catalog checks, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_membership_stripe_price_create: creates and selects one replacement monthly membership Stripe Price through the server route with exact confirmation, server-side Stripe credentials, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_membership_tier_create: creates one inactive membership tier draft through the shared envelope with exact confirmation, profile and benefit copy, monthly amount, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_membership_tier_update: updates one membership tier profile or benefit copy through the shared envelope with exact confirmation, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_membership_tier_archive_state: archives or restores one membership tier for future joins through the shared envelope with exact confirmation, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_shop_product_create: creates one safe shop product through the shared envelope with exact confirmation, observed product ids, duplicate id/slug checks, idempotency, reason, audit correlation, and scoped/admin credentials. It never sets raw download URLs, external URLs, Stripe Price ids, checkout sessions, fulfillment execution, orders, refunds, or credits. - fanful_creator_shop_product_visibility_update: toggles active/show-in-shop state on one editable shop product through the shared envelope with exact confirmation, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_shop_product_details_update: updates safe existing shop product details through the shared envelope with exact confirmation, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. It can change copy, inventory tracking/count, fulfillment note, download display metadata, and sort order; price and Stripe mapping use the separate shop product Stripe Price tools, and it never changes raw download URLs, external URLs, product kind/id, checkout, fulfillment execution, orders, or refunds. - fanful_creator_shop_product_stripe_price_select: selects or clears one compatible app-state Stripe Price mapping on an existing shop product through the shared envelope with exact confirmation, stale-state, catalog checks, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_shop_product_stripe_price_create: creates and selects one replacement one-time shop product Stripe Price through the server route with exact confirmation, server-side Stripe credentials, existing Product context, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. - fanful_creator_entitlement_metadata_update: updates one non-default community channel's signed-in or membership-tier access metadata through the shared envelope with exact confirmation, stale-state, idempotency, reason, audit correlation, and scoped/admin credentials. It never creates tiers, changes prices, grants credits, changes paid rooms, or revokes memberships. - fanful_listener_community_messages_read: reads the latest visible messages from an accessible community channel such as #general or #intros, defaulting to 10 messages. - fanful_listener_community_message_post: posts one visible community message or reply after scoped/session listener auth, exact public-message confirmation, acknowledged risk, idempotency, and channel-access checks. - fanful_creator_embedded_room_roster_update: executes a confirmed embedded-room invite, co-host, stage, removal, or restore change through the shared envelope with exact confirmation, idempotency, stale-state, reason, audit correlation, and scoped/admin credentials. - fanful_listener_live_support_preview: reads live-room support CTA readiness and generic support/donation purchase preview copy before confirmed checkout. - fanful_listener_checkout_confirmation_render: renders a ChatGPT Apps SDK confirmation summary for support, membership, or signed-CD shop checkout starts before the separate scoped listener checkout write tool. - fanful_listener_support_checkout_start: starts support-only checkout after exact listener confirmation, idempotency, reason, audit correlation, and scoped listener credentials. - fanful_listener_membership_checkout_start: starts membership checkout after exact listener confirmation, idempotency, reason, audit correlation, server owned Stripe Price mapping, and scoped listener credentials. - fanful_listener_shop_checkout_start: starts signed-CD shop checkout after exact listener confirmation, idempotency, reason, audit correlation, active shop product checks, and scoped listener credentials. - fanful_listener_purchase_link_status: reads redacted support, membership, or shop checkout intent status by reference or idempotency key after checkout start. - fanful_live_schedule_preview: previews live create, schedule edit, or reschedule impact without mutating live state or audit rows, while redacting stream and replay fields. - fanful_creator_live_schedule_create: executes confirmed new live-event creation with shared-envelope confirmation, idempotency, blocker checks, and audit correlation. - fanful_creator_live_schedule_update: executes a confirmed existing-event live schedule change with shared-envelope confirmation, idempotency, stale-state, and audit correlation. - fanful_live_status_preview: previews go-live, end, cancel, or scheduled-status impact without mutating live state, sockets, or audit rows. - fanful_creator_live_status_update: executes a confirmed live status change with shared-envelope confirmation, idempotency, stale-state, and audit correlation. ## Current API surfaces | Surface | HTTP endpoint | MCP resource | Status | | --- | --- | --- | --- | | Community chat | /api/agent/community-chat | fanful://agent/community-chat/manifest | Shipped | | Embedded rooms | /api/agent/embedded-rooms | fanful://agent/embedded-rooms/manifest | Roster writes ready | | Live controls | /api/agent/live-controls | fanful://agent/live-controls/manifest | Schedule previews and status writes ready | | Creator commerce | /api/agent/creator-commerce | fanful://agent/creator-commerce/manifest | Publisher referral reads plus price, availability, Stripe mapping, tier lifecycle, and channel tier-access writes ready | | Artist analytics | /api/agent/artist-analytics | fanful://agent/artist-analytics/manifest | Authorized aggregate summary ready | | Media upload sessions | /api/agent/media-upload-sessions | fanful://agent/media-upload-sessions/manifest | Confirmed session handoff ready | | Listener experience | /api/agent/listener-experience | fanful://agent/listener-experience/manifest | Entitlements, profile reads, display-name writes, and checkout/support slices shipped | | Member idea board | /api/agent/idea-board | fanful://agent/idea-board/manifest | Member submit/vote writes ready | | ChatGPT app readiness | /api/agent/chatgpt-app | fanful://agent/chatgpt-app/manifest | Shipped readiness manifest | | Action contracts | /api/agent/action-contracts | fanful://agent/action-contracts/manifest | Shipped contract manifest | | Workflow triggers | /api/agent/workflow-triggers | fanful://agent/workflow-triggers/manifest | Manifest, subscription registry, manual test delivery, and member.idea.submitted runtime fan-out shipped; other families planned | | Agent sessions | /api/agent/sessions | fanful://agent/sessions/manifest | Shipped manifest, sample event-log readback, storage planned | | Sync jobs | /api/agent/sync-jobs | fanful://agent/sync-jobs/manifest | Manual Stripe catalog drift worker and public work-log feed shipped | | Work-log feed | /api/agent/sync-feeds/work-log | HTTP only | Public agent-sync-feed.v1 upserts | | Domain setup | /api/agent/domains | fanful://agent/domains/manifest | Read-only MCP domain setup manifest and focused `fanful_domain_setup_read` tool | ## ChatGPT app direction Fanful is not submitted as a ChatGPT app yet. The current shipped slice is a readiness manifest at /api/agent/chatgpt-app plus public MCP transport at /mcp. Hosted agent workers are not a ChatGPT-specific runtime; arbitrary code and custom reasoning stay external to Fanful until a concrete worker family has approval, cancellation, retries, limits, audit, and rollback defined. Still planned before submission: - OAuth or first-party session mapping for private creator/listener reads. - Tool descriptor metadata, security schemes, invocation copy, and optional UI resources where they help. - Widget CSP/domain metadata and screenshots for UI-heavy workflows. - More confirmed write routes beyond live status, lesson price, lesson Stripe Price mapping/creation, membership tier lifecycle, community channel tier-access metadata, and listener display-name updates that enforce auth, confirmation, audit attribution, idempotency, rate limits, and redaction. ## Markdown and sitemap status Current markdown-readable Fanful pages include /fanful.md, /features.md, /pricing.md, /docs.md, /developers-and-agents.md, /compare.md, /compare/all.md, focused comparison pages, migration guides, guide posts, and the /agent-docs/fanful-agent-ingestion-qa.md answer-quality smoke matrix. The browser roadmap ships at https://fanful.net/roadmap, and the live roadmap JSON ships at /api/roadmap. The roadmap markdown mirror ships at /roadmap.md. The Fanful root sitemap is generated from marketing paths and includes /docs, /developers-and-agents, and model-readable mirrors where they exist. docs.fanful.net also serves its own developer-docs sitemap. ## Safety and authorization boundaries - Do not automate private web UI when a server-side manifest or MCP tool exists. - Do not pass admin secrets as prompt-visible tool input. - Admin credentials, when enabled locally, stay in the MCP process environment. - Do not expose Stripe ids, payment identifiers, raw listener ids, raw media URLs, private invite links, media tokens, or device ids in model-visible logs. - Artist analytics summaries are private creator/admin reads. Use /api/agent/artist-analytics instead of scraping /admin/analytics, and do not expose raw listener rows, Better Auth ids, anonymous ids, session ids, device ids, payment ids, media URLs, or raw event logs. - Public posts, moderation, creator speech, checkout, unsupported pricing, domain registration, destructive changes, and billing-impacting actions require explicit confirmation and audit behavior before becoming executable tools. - New live-event creation, existing-event live schedule changes, and go-live/end/cancel/restore status changes are executable only through the confirmed live wrappers with preview, confirmation, idempotency, stale-state where relevant, and audit correlation. - Workflow triggers are redacted event notifications, not write permission. A trigger should make an agent verify the signature, use event/delivery ids for retry idempotency, and read the linked Fanful manifest before acting. Catalog drift triggers link sync-job checkpoints to the creator-commerce action contract so agents can summarize drift without writing provider state. Public, destructive, checkout, moderation, or creator-speech writes still require the current action contract plus the shared confirmed-write envelope. - Agent sessions are redacted run histories and pending-approval records, not hosted execution. Sample event logs are readable at /api/agent/sessions/{sessionId}/events; storage-disabled write routes name the expected contract without echoing private request bodies. Multi-step work should record session/event summaries, approvals, completed tool calls, and cancellation without exposing raw listener ids, Better Auth ids, Stripe ids, media URLs, invite tokens, private message bodies, or admin credentials. - Sync jobs are redacted checkpoint and drift-report records, not provider write permission. Agents can run the first-party Stripe catalog app-reference drift worker, store opaque cursors exactly as returned, expect duplicate-safe resume pages, and never pass provider credentials, raw payment ids, media handles, or private database identifiers as prompt-visible input. - Lesson/coaching price cents are executable only through the confirmed creator price wrapper after a fresh preview, exact confirmation, idempotency, stale-state, and audit correlation. Existing lesson Stripe Price mappings are executable only through the confirmed selection wrapper after a fresh catalog read, exact confirmation, stale-state, idempotency, and audit correlation. Replacement lesson Stripe Price creation is executable only through the confirmed server wrapper with Stripe credentials, existing Product context, exact confirmation, stale-state, idempotency, and audit correlation. Membership tier creation starts inactive, and profile/archive plus non-default community channel tier-access metadata writes are executable only through their confirmed wrappers. Safe shop product creation, visibility/details, and compatible one-time Stripe Price writes are executable only through their confirmed wrappers. Service policy, raw product URL/checkout, credit, cancellation, refund, and broader entitlement writes remain unavailable. - ChatGPT clients should not get a special write path. The same MCP-backed action contracts should apply across ChatGPT, CLI, Codex, Claude Code, web, iOS, and Android.