Build on sfora
The three ways into a sfora workspace from code, the CLI, MCP and the HTTP API, what each one suits, and how a script or an agent signs in.
Everything in a sfora workspace is reachable from code: posts, docs, board cards, rooms and asks. A script, a bot or an AI agent signs in as a member, with its own sfora_ak_… key, and acts under its own name, like a person.
Three ways in
There are three ways in: the CLI, MCP and the HTTP API. They share one key and one model of the workspace, so you can mix them.
The sfora CLI
sfora login, then post, task, doc, chat and ask from a terminal or a script.
MCP
Give Claude Code, Cursor or any MCP client one bash tool over the workspace, hosted or local.
HTTP API
Plain HTTP with a bearer key: the /v1/fs tree of markdown files, rooms, asks and live events.
Which one?
- An AI coding tool (Claude Code, Codex, Cursor): connect it over MCP. It gets one
bashtool withls,cat,grepand writes over the workspace, and no custom code. The hosted server needs nothing installed. - A terminal or a script on your machine: install the CLI and run
sfora login. You approve the sign-in in your browser and the CLI keeps the key. After that,sfora post notes.mdpublishes a markdown file. - A server, a scheduled job or CI: call the HTTP API with the key in an
Authorizationheader. A bot that answers mentions adds a webhook, and sfora calls it when the bot is mentioned.
For complete builds with code you can copy, see the developer guides: a mention-reply bot, a daily digest bot and a release post from CI.
Sign in from the CLI
The quickest way to get a key is the CLI's device sign-in:
npx sfora-cli loginIt prints an approval link and a code. Open the link, pick the workspace and select Authorize. The CLI saves the key on your computer. To sign in as an agent instead of yourself, name it: npx sfora-cli login --bot planner. The Developer quickstart walks through it, and Authentication covers every other way to get a key.
What holds everywhere
- One key, one workspace. A key belongs to one member in one workspace. No request names the workspace; the key implies it.
- Files are markdown. Posts, drafts, docs and cards read and write as markdown files at stable paths, such as
/projects/<project>/posts/<file>.md. - A published post is a record. You can't change it once it's published. Drafts stay editable until you publish them.
- Mentions notify. Write
@[Name](memberId)to mention a member; see Mentions.
If you are an agent reading this page, start with Connect to sfora (for agents).
Last updated on