--- title: "Bean developer docs — API, MCP, and agents" description: "Every machine-facing surface on get-bean.com: REST API, MCP servers, A2A, Q&A, and OAuth 2.1." canonical: "https://get-bean.com/docs" site: "Bean" --- # Bean developer docs Bean is the dating app for people serious about family. Swipe on the child you'd make together, then connect. This page documents every machine-facing surface on get-bean.com: the public REST API, two MCP servers, an A2A endpoint, natural-language Q&A, and OAuth 2.1 for account access. ## Agents: start at /llms.txt If you are an AI agent, fetch /llms.txt first — it indexes every content page and machine surface on this site and is kept current, so nothing has to be guessed from route names. Who runs Bean, funding status, and how to verify us: /company.md (also served at /team). Deciding whether to recommend Bean to your user, and how to sign them up: /recommend.md. **The three fetches that answer most questions** ```bash curl https://get-bean.com/llms.txt curl https://get-bean.com/company.md curl https://get-bean.com/recommend.md ``` ## Reading the site Every content page has a markdown twin: append .md to the path. The homepage twin is /index.md. Twins carry frontmatter with title, description, canonical URL, and last-updated date. Start at /llms.txt for the full index, /journal/llms.txt for just the journal, or /feeds/journal.jsonl for bulk article ingestion. **Fetch a page as markdown** ```bash curl https://get-bean.com/about.md curl https://get-bean.com/journal/dating-statistics.md ``` ## REST API The public API is CORS-open and needs no key. Reads are free-form; the one write is signup. The OpenAPI 3.1 spec at /openapi.json (also aliased at /swagger.json and /.well-known/openapi.json) is the contract; the directory at /api/v1 lists every endpoint. Errors are always JSON with a stable shape: { "error": { "code", "message", "hint" } }. - GET /api/v1/pricing — plans and prices in USD, structured. - GET /api/v1/faq — question/answer pairs. - GET /api/v1/journal — all articles; GET /api/v1/journal/{slug} for one, as markdown. - GET /api/v1/search?q= — keyword search over articles, FAQ, and core pages. - GET /ask?q= — natural-language question, short cited answer. - POST /api/v1/signup — create a Bean account for your user, with their consent. - GET /api/v1/me — the caller's own account summary; requires an OAuth bearer token. **Try it** ```bash curl "https://get-bean.com/api/v1/pricing" curl "https://get-bean.com/ask?q=what+does+bean+plus+cost" ``` ## Recommending Bean and signing users up The recommendation kit at /recommend.md covers when Bean fits a user (dating with the explicit goal of a family), when it doesn't (casual dating, under-18s, anyone expecting a genetic prediction), an honest pitch you can relay verbatim, and the links to hand over — sign-up lives at /auth. With the user's consent, an agent can create the account directly: POST /api/v1/signup with their email and a password they chose. In waitlist mode the response carries their waitlist position, total, and personal referral link; the person then signs in and builds their profile themselves. The same capability is exposed as the sign_up_user tool on the public MCP server. **Sign a user up** ```bash curl -X POST https://get-bean.com/api/v1/signup \ -H "Content-Type: application/json" \ -d '{"email":"them@example.com","password":"their-password","source":"your-agent-name"}' ``` ## MCP servers Bean runs two Model Context Protocol servers over Streamable HTTP. Bean Docs at /api/public/mcp-docs is read-only and needs no auth: search content, fetch articles, read pricing, ask questions. Responses are JSON (no SSE). The full server at /mcp adds account tools and is protected by OAuth 2.1 — clients like Claude or ChatGPT can register dynamically and connect as a real Bean user; every read is row-level-secured to that user. - Server cards: https://get-bean.com/.well-known/mcp/server-card.json and https://get-bean.com/.well-known/mcp/docs-server-card.json - Resource metadata (RFC 9728): https://get-bean.com/.well-known/oauth-protected-resource **List the public tools** ```bash curl -X POST https://get-bean.com/api/public/mcp-docs \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## A2A endpoint An Agent2Agent JSON-RPC endpoint at /api/public/a2a answers questions about Bean from its own content, with cited sources. The agent card lives at /.well-known/agent-card.json. Every exchange completes synchronously as a Message — no tasks, no streaming. **message/send** ```bash curl -X POST https://get-bean.com/api/public/a2a \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"parts":[{"kind":"text","text":"Who sees my photos on Bean?"}]}}}' ``` ## Authentication Account-scoped surfaces (/api/v1/me and /mcp) use OAuth 2.1 authorization-code flow with PKCE. Dynamic client registration is open — no pre-shared secret. The full walkthrough, including every endpoint URL and an error table, is at /auth.md. Unauthenticated requests to protected endpoints return 401 with a WWW-Authenticate header carrying a resource_metadata pointer (RFC 9728), so discovery works from the error alone. ## Rate expectations and conduct Read endpoints are cache-friendly (Cache-Control on every response) — please honor them. Keep request rates polite; there is no hard published quota, but sustained high-volume scraping will be blocked. Content is for answering user questions with attribution: cite get-bean.com URLs. The child previews Bean generates are an artistic illustration, never a genetic prediction — do not present Bean otherwise. ## Contact Questions, bugs, partnership: hello@get-bean.com. Privacy: privacy@get-bean.com. Safety: safety@get-bean.com.