BriefDesk: multi-agent research briefs you can trust

You give BriefDesk a topic. A team of AI agents handles the brief:

• The Supervisor plans it, and you approve the plan.

• The Researcher reads the web and your own documents (through MCP).

• The Writer drafts a cited brief.

• The Reviewer critiques it.

• The Verifier checks every citation against the text of the page it came from.

You chat with the agents live the whole time. While they work you can steer them, ask questions or request a revision. When the brief is ready, ask for it in any format, for example "as Word", "slides for my manager" or "a dark infographic".

Why

Writing a researched brief by hand takes hours of searching, reading, writing and reviewing. Plain chatbots are fast, but their answers have no sources, or sources they made up, so nobody can sign off on them.

BriefDesk's promise is fast and checkable:

• The plan is human-approved.

• Every claim carries a numbered source.

• Each citation is verified against the page it came from.

• Everything the agents did is visible.

Related MCP server: AI Material Cabinet MCP

What it does

Architecture

 HTML/CSS/JS SPA ──REST + WebSocket──►  FastAPI (one process)
                                         ├─ auth: short-lived JWT in memory + rotating refresh token in an httpOnly cookie
                                         ├─ chat hub: events persisted first, then fanned out; replay after reconnect
 Claude Desktop / Code ──MCP (stdio)──►  ├─ mcp_server/ (thin client over the same REST API, personal API token)
                                         └─ job runner: agent pool + task pool (threads)
                                                 │
                       LangGraph StateGraph + SQLite checkpointer (pause · steer · resume · retry · revise)
   Supervisor ─► Researcher (ReAct: web_search, read_page, MCP tools) ─► Writer ─► Reviewer ─► Verifier ─► finalize
        ▲________________________ every worker returns to the Supervisor _________________________│
                                                 │
   LLM gateway (Groq): run budget · cache · circuit breaker per model · token pacer per model · bounded retry
   Conversation agent (intent router) · Publisher agent (format → shape → render)
                                                 │
   SQLAlchemy + Alembic: users · briefs · runs · events · sources · report_versions · citations · files · api_tokens

More detail is in docs/ARCHITECTURE.md.

Stack: Python · FastAPI · WebSockets · LangGraph · LangChain · Groq (gpt-oss-120b, gpt-oss-20b, qwen) · MCP (Python SDK 2) · SQLAlchemy · Alembic · reportlab · python-docx · python-pptx · openpyxl · matplotlib · vanilla HTML/CSS/JS (no build step, no CDN)

Run it locally (Windows / macOS / Linux)

Requires Python 3.11+.

git clone https://github.com/mani2810/briefdesk.git
cd briefdesk
python -m venv .venv
.venv\Scripts\activate            # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

Option A – offline demo (no API key, no internet): the AI and the web pages are scripted, so the whole UI works end to end.

python run.py --demo

Option B – the real thing (free Groq key):

copy backend\.env.example backend\.env      # macOS/Linux: cp backend/.env.example backend/.env
# edit backend/.env and set GROQ_API_KEY=...   (free key: https://console.groq.com/keys)
copy mcp_servers.example.json mcp_servers.json   # optional: the example MCP knowledge base
python run.py

Open http://localhost:8000 and log in with demo@briefdesk.dev / Research2026. The admin account is admin@briefdesk.dev / ChangeMe!2026; change that password in Settings.

About the Groq free tier

Groq's free tier allows about 8,000 tokens per minute per model. BriefDesk is built for that limit:

• Agents are spread across three models. Routing, chat and notes use qwen; the researcher uses gpt-oss-20b; the writer and reviewer use gpt-oss-120b. Each model has its own token allowance.

• The gateway paces itself. When it nears a limit it waits and shows "Pacing for the Groq free-tier token limit…" in the chat, instead of failing with 429 errors.

• The supervisor only calls the LLM at real decision points. It uses a deterministic state machine otherwise.

• The researcher keeps its history compact. Older tool results are summarised before each call.

A standard brief takes roughly 2–5 minutes on the free tier. If a model is still exhausted, the run degrades gracefully instead of failing: deterministic routing, research without the model, and the final draft is always verified. Progress is checkpointed, so "retry" continues from the last completed step.

Use BriefDesk from Claude (MCP server)

1. In BriefDesk, open Settings & API and create a token. The dialog shows a ready-made config.

2. In Claude Desktop, open Settings → Developer → Edit config and add:

{
  "mcpServers": {
    "briefdesk": {
      "command": "C:\\path\\to\\briefdesk\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\briefdesk\\mcp_server\\briefdesk_mcp.py"],
      "env": { "BRIEFDESK_URL": "http://127.0.0.1:8000", "BRIEFDESK_TOKEN": "bd_..." }
    }
  }
}

The server provides five tools: create_brief, get_brief, list_briefs, ask (question, revise or steer) and export_brief. Exports are saved to ~/Downloads/BriefDesk. The MCP server goes through the same REST API, so quotas, rate limits and ownership rules apply. An API token cannot change passwords, manage tokens or reach admin endpoints.

Plug your own tools into the researcher (MCP client)

mcp_servers.json uses the same shape as Claude Desktop's config, plus an allow-list:

{ "servers": { "company_kb": {
    "command": "python", "args": ["examples/company_kb_mcp/server.py"],
    "allowed_tools": ["search_company_docs"], "description": "Internal market notes" } } }

Here is how it behaves:

• New tools appear automatically. The researcher sees company_kb__search_company_docs next to web search; MCP results become citable sources and show an MCP badge.

• A broken server is isolated. If a server fails to start, it is logged and skipped.

• Tool output is untrusted data. The prompts treat it like web content and never follow instructions inside it.

Production-minded details

• Security:

  • The refresh token is an httpOnly, SameSite=Strict, path-scoped cookie with rotation and reuse detection. The access token is kept in memory only.

  • Refresh and logout require a custom header, there are no CORS grants, and a strict CSP is set (script-src 'self', no inline scripts).

  • WebSockets use 60-second single-use tickets plus an Origin check.

  • Logins are protected by per-(email, IP) lockout, bcrypt and a constant-time compare.

  • The page fetcher has an SSRF guard: public IPs only, re-checked on every redirect, with size and time caps.

  • Spreadsheet exports are protected against formula injection.

  • The Markdown renderer is safe by construction: everything is escaped and only allow-listed tags are emitted.

  • Users are isolated (a 404 for anything that isn't theirs) and secrets are redacted from logs.

• Reliability:

  • Agent runs never block HTTP requests or sockets.

  • LangGraph checkpoints make pause, resume and retry survive restarts.

  • On startup, the server recovers interrupted runs.

  • Every loop is bounded: a per-run LLM-call budget, an iteration guard and a research-round limit.

  • Each model has its own circuit breaker.

• Observability: per-request ids, JSON logs, an audit log, admin dashboards showing tokens and calls per agent, pacing waits and failed runs.

• Quality:

  • The tests run fully offline (scripted LLM plus sample pages). They cover the whole flow: plan → approval → agents → verified report → chat, exports, revision, steering, cancel/retry and user isolation.

  • CI runs on Python 3.11 and 3.13.

cd backend && pytest -q

Project layout

backend/app/
  agents/      graph.py (Supervisor + workers), verifier.py, publisher.py, prompts.py, schemas.py
  llm/         gateway.py (guards, pacing), fake.py (offline brain)
  tools/       web.py (search, safe fetch), registry.py, mcp_client.py
  renderers/   pdf, docx, pptx, image, xlsx/csv, html, md, json, txt
  services/    runner.py (jobs + checkpoints), chat.py (conversation agent), hub.py (live fan-out), briefs.py
  api/         REST routes + WebSocket
frontend/      index.html, css/app.css, js/ (app, chat, report, admin, settings, markdown, socket, api)
mcp_server/    briefdesk_mcp.py   - BriefDesk as an MCP server
examples/      company_kb_mcp/    - example MCP server for the researcher

License

Free for learning, research and personal use under the PolyForm Noncommercial License 1.0.0. Commercial use requires permission. Open a commercial-licence request.