@briefgate/mcp
A client-intake service: create a branded portal, email a client a link, chase them automatically, and get typed assets (files, copy, credentials, structured data) back into your agent.
Create intakes (
define_intake) — declare items the client must supply (text, longtext, file, file_list, image, color_list, select, multiselect, boolean, url, secret, structured JSON Schema), with constraints like formats, sizes, char limits, counts, and regex patterns; set client details, due date, branding, language, retention, custom email copy, and a client brief.Automated chasing — pick a reminder cadence (default, gentle, aggressive, custom, off), quiet hours, max reminders, and clock-anchored send times; the client is emailed and nudged until everything arrives.
Track progress (
get_intake_status) — per-item status, submitted counts, chase history, and when the client last opened the portal.Collect results (
get_intake_results) — typed values plus 24-hour signed file URLs; secrets revealed in plaintext exactly once;only_newandinclude_pendingfilters.Ask for fixes (
request_revision) — send the client a note on a specific item that needs resubmitting.Manual nudges (
send_chase) — an extra reminder outside the automatic schedule.Evolve a sent intake —
add_items,update_item(change type/label/constraints, with guard against discarding submitted answers),update_intake(due date, cadence, brief, client fields).Ask the developer, not the client —
assignee: "owner"decision items with an optionalproposedanswer, recorded asagent_proposaluntil a human answers in the dashboard.Manage people (
manage_recipients) — add, remove, or reinstate additional recipients who share the portal link.Organize —
list_intakeswith filters and search, pluslist_folders/create_folderfor grouping by client or project.Get notified (
manage_webhook) — register HTTPS endpoints forintake.completed,item.submitted,client.viewed,chase.bounced,intake.overdue,intake.stalled; signed with HMAC-SHA256 and verifiable via the package's@briefgate/mcp/webhookhelper. Otherwise poll on a schedule.Authentication —
login(two-phase device flow) andlogout, or supplyBRIEFGATE_API_KEY.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@briefgate/mcp Set up a client intake for logo, copy, and WordPress credentials."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
BriefGate
Client intake — from your browser, or from your AI coding agent.
Your agent can build the website. BriefGate gets the missing things from the client.
No agent? You don't need one. Everything below can be done by hand at app.briefgate.dev: build the request, send the link, watch answers arrive, download the results as one ZIP — no code, no API key, no MCP client. This package is for the other way of working, where an agent does it for you. See the dashboard quickstart.
Claude Code / Cursor / Codex → BriefGate → Client portal
→ Files · copy · credentials · structured data → Agent continues building
Watch as MP4 (25 s) · Full 47 s walkthrough
Website · MCP reference · llms.txt · Guides and checklists
The problem
Agents are fast. The bottleneck is the human on the other side of the project.
Somewhere in the middle of building, the agent needs something only the client has: a logo, homepage copy, brand colors, opening hours, hosting credentials, an API key, a piece of structured data like a price list. None of that exists in the chat, and none of it can be guessed.
The usual move is to stop and ask the developer to go chase the client by email. Instead, the agent creates a BriefGate intake. BriefGate emails the client, collects what comes back, chases automatically when it doesn't, and returns typed results the agent can use directly. The agent keeps building in the meantime.
Related MCP server: hireme-mcp
Quickstart
Claude Code — hosted, no key to manage:
claude mcp add --transport http briefgate https://mcp.briefgate.dev/mcpThen run /mcp in Claude Code, pick briefgate, and choose Authenticate.
Claude apps, Cowork and Claude Code — from the Claude directory: BriefGate is listed as a connector and as a Claude Code plugin. The plugin installs the same hosted endpoint plus the collect-from-client skill. The directory reads it from the claude-plugin branch, which a GitHub Action rebuilds from main with scripts/build-claude-plugin-branch.sh.
Claude Code — local package:
claude mcp add briefgate -- npx -y @briefgate/mcp
npx -y @briefgate/mcp loginPrefer to skip sign-in entirely? Get a key at briefgate.dev (free tier, no card) and pass it as BRIEFGATE_API_KEY.
Cursor — add to .cursor/mcp.json:
{
"mcpServers": {
"briefgate": {
"command": "npx",
"args": ["-y", "@briefgate/mcp"]
}
}
}Then run npx -y @briefgate/mcp login, or ask the agent to call the login tool.
Codex:
codex mcp add briefgate --env BRIEFGATE_API_KEY=bg_live_xxxxx -- npx -y @briefgate/mcpGemini CLI — installs as an extension from this repo's gemini-extension.json, pointed at the hosted endpoint:
gemini extensions install https://github.com/sekera-radim/briefgate-mcpIt authenticates the same way as the other hosted clients above — via OAuth, on first use. The extension also ships GEMINI.md, a context file that tells the model what BriefGate is and when to reach for it.
By default gemini extensions install fetches the repo's latest GitHub Release rather than the main branch; if that release predates the current gemini-extension.json and the command reports a missing configuration file, install from main directly instead: gemini extensions install --ref main https://github.com/sekera-radim/briefgate-mcp.
Claude Desktop — one-click install as a Desktop Extension (.mcpb), running the local @briefgate/mcp package instead of the hosted endpoint. Build details: see MCPB bundle below.
Cursor — as a plugin from this repo's .cursor-plugin/plugin.json, which bundles the same MCP config together with the collect-from-client skill below.
Any Agent Skills-compatible tool (OpenAI Codex, GitHub Copilot / VS Code, Cursor, Gemini CLI, and other clients on that standard) — install the collect-from-client skill with the skills CLI:
npx skills add https://github.com/sekera-radim/briefgate-mcp/tree/main/skills/collect-from-clientThe bare owner/repo shorthand the CLI's own docs show does not work against this layout as of skills@1.5.26 — it either 404s against its registry or, given the plain repo URL, clones the whole repo and reports "No SKILL.md found" because ours lives a directory deeper than the root. The full /tree/main/skills/<name> URL above is what actually installs it; verified by running it in an empty scratch directory before documenting it. This copies SKILL.md into that tool's local skills directory; the skill still assumes the briefgate MCP server (see the client-specific instructions above) is configured separately.
Full setup details, manual config, and API-key precedence: see Reference below.
For agents reading project instructions (AGENTS.md, Copilot, Cursor rules)
If your agent reads a project instructions file instead of (or in addition to) MCP tool descriptions or Agent Skills, add this block to your AGENTS.md, .github/copilot-instructions.md, or .cursor/rules:
## BriefGate
BriefGate (MCP server `briefgate`, or `npx @briefgate/mcp`) collects files,
text, choices, or credentials from a human who is not in this conversation
(a client, colleague, or customer) — it emails them a no-account portal link
and chases them automatically until everything is submitted.
Use it when a task is blocked on input only that outside person can supply,
especially if they may take days and need reminders. Do not use it when the
information is already available, or when the person who should answer is
the user you're talking to.
Flow: `define_intake` (with items) -> tell the user it was sent ->
`get_intake_status` later ("not ready" is normal, not an error) ->
`get_intake_results` once completed. `request_revision` for a bad item.
Secret items are revealed in plaintext exactly once.Example: building a client's website
An agent is building a website for a restaurant. It has the layout and the booking flow, but it still needs the logo, a hero photo, the opening hours, a short description of the restaurant, the social media links, and admin access to the client's WordPress install. It calls define_intake:
{
"project_name": "Website for Trattoria Bella",
"client": { "email": "owner@trattoriabella.example", "name": "Marco", "language": "en" },
"items": [
{ "key": "logo", "type": "image", "label": "Restaurant logo",
"constraints": { "formats": ["svg", "png"], "min_width": 512 } },
{ "key": "hero_image", "type": "image", "label": "Hero photo for the homepage" },
{ "key": "opening_hours", "type": "structured", "label": "Opening hours",
"schema": { "type": "object", "properties": { "mon_fri": { "type": "string" }, "sat": { "type": "string" }, "sun": { "type": "string" } } } },
{ "key": "about_copy", "type": "longtext", "label": "Short description of the restaurant" },
{ "key": "social_links", "type": "structured", "label": "Social media links" },
{ "key": "wp_admin", "type": "secret", "label": "WordPress admin credentials" }
]
}From there, BriefGate (1) creates a branded portal, (2) emails the client, (3) validates each asset as it comes in, (4) chases the client automatically until everything is submitted, and (5) notifies the agent when it's done.
The agent keeps building the layout, the booking flow, and everything else that doesn't depend on this — then calls get_intake_results(intake_id) and gets back typed data and signed URLs for the files, plus a one-time reveal of the WordPress credentials. It stores the secret and continues.
Why not a form?
Generic form | BriefGate |
Human creates the form | Agent declares what it needs |
Human reads results | Agent consumes typed results |
Generic answers | Typed items |
Manual follow-up | Automatic chasing |
Spreadsheet mindset | API / MCP workflow |
Credentials are awkward | Secret item + controlled reveal |
Human workflow | Agent workflow |
BriefGate is not trying to replace every form builder. It is designed for the point where an AI agent needs information from a human.
Free tier, no card required. BriefGate is a hosted service — this repository is the open-source MCP client, MIT licensed. Sign up at briefgate.dev.
Reference
Everything below is unchanged technical detail: manual setup, environment variables, HTTP/OAuth mode, the full tool reference, webhooks, pricing, and legal.
Claude Code: manual setup and API keys
Paste an API key (for CI, scripts, or if you'd rather manage the key yourself). Get one at briefgate.dev (free tier available, no card required):
claude mcp add briefgate \
-e BRIEFGATE_API_KEY=bg_live_... \
-- npx -y @briefgate/mcpOr add manually to ~/.claude/settings.json:
{
"mcpServers": {
"briefgate": {
"command": "npx",
"args": ["-y", "@briefgate/mcp"],
"env": {
"BRIEFGATE_API_KEY": "bg_live_..."
}
}
}
}BRIEFGATE_API_KEY (or --api-key on the command line), if set, always takes precedence over a key login stored locally — running login while one is configured just says so instead of doing anything.
Verify it loaded — run /mcp in Claude Code and look for briefgate with 15 tools.
The same local-package and API-key setup works for any MCP client that runs the package locally (Cursor, Codex, others) — register it with no key at all and run login, or paste BRIEFGATE_API_KEY into that client's own MCP config the same way.
Sign in without an API key
Two ways to get a key onto this machine without pasting one — both run the same device-authorization flow (RFC 8628) against the same credential file, so pick whichever fits how you're using the package.
From a terminal — the login / logout subcommands:
npx -y @briefgate/mcp login # prints a code + URL, waits for approval, saves the key
npx -y @briefgate/mcp logout # removes the local key, best-effort revokes it remotelylogin blocks until you approve it (or it times out at 10 minutes), then prints Signed in as <account_name> and exits 0 — or prints why it didn't work (denied, expired, an error) and exits 1. logout always removes the local copy; it also sends DELETE /v1/keys/current using that same key to revoke it server-side, and if that call fails (no network, API unreachable) it says so and points at the BriefGate dashboard instead of leaving you unsure whether the key is still live.
From an agent — the login / logout tools (see Tools):
Same flow, for a client that can't block a terminal on your click. login is two-phase because a tool call can't sit open for minutes:
The first call starts the flow and returns immediately with the code and URL. A browser is opened automatically where possible.
Call
loginagain — any time, or once you've approved it — to check progress. While it's still waiting, it says so; once approved, that same call reports success and the key is saved. No restart needed: the very next tool call is signed in.
logout as a tool does exactly what the subcommand does, including the best-effort remote revoke.
Either way, the key lands in ~/.briefgate/credentials.json (directory mode 0700, file mode 0600; override the path with BRIEFGATE_CREDENTIALS_FILE), keyed by which BriefGate server it's for so a staging BRIEFGATE_BASE_URL and production never collide. An explicit key always wins over a stored one — --api-key, then BRIEFGATE_API_KEY, then whatever login last saved — and login says so instead of running the flow when one of those is already set. Neither the subcommands nor the tools apply to the shared hosted endpoint (mcp.briefgate.dev) — see Hosted endpoint + OAuth, where connecting a client triggers real OAuth instead.
Environment variables
Variable | Required | Default | Description |
| No | — | API key ( |
| No |
| Override for staging or local development. |
| No |
| Where |
| No | unset | Set to |
| No | — | Set to |
| No |
| Port for HTTP mode. |
| No | — | Publishes the server as a shared, multi-customer OAuth endpoint. See Hosted endpoint + OAuth. |
| No |
| The OAuth authorization server advertised to clients in published mode. Defaults to |
--api-key bg_live_... is also accepted on the command line, ahead of BRIEFGATE_API_KEY in priority. login and logout are also accepted as the first command-line argument (npx @briefgate/mcp login), instead of --http/no flag.
HTTP (Streamable HTTP) mode
For remote or multi-session deployments, start the server in HTTP mode:
BRIEFGATE_API_KEY=bg_live_... npx @briefgate/mcp --http --port 3000The server binds to 127.0.0.1 only and includes DNS-rebinding protection. Behind a reverse proxy, terminate TLS there and forward to the local port — do not expose the port directly.
Hosted endpoint + OAuth
Set BRIEFGATE_MCP_PUBLIC_HOST to the hostname the server is published under and
it becomes a shared, multi-customer endpoint: each caller sends its own key as
Authorization: Bearer bg_live_... (an OAuth access token, for this API, is
that same key — see below), and the server speaks to the BriefGate API as that
caller. The public instance is https://mcp.briefgate.dev/mcp.
BRIEFGATE_MCP_PUBLIC_HOST=mcp.example.com npx @briefgate/mcp --http --port 3000Several things change, on purpose:
the listener binds
0.0.0.0and the Host guard accepts that name, because a server behind a reverse proxy is reached by its public name;the
BRIEFGATE_API_KEYfallback and the locallogincredential are both switched off. Leaving either on would let an anonymous caller spend the operator's key, or read whatever the machine's ownloginlast stored;login/logout, tools and subcommands alike, are unavailable — connecting a client triggers real OAuth instead, described below;the server becomes an OAuth 2.1 resource server, per the MCP authorization spec, so an OAuth-aware client can add it with nothing but the URL. This package never runs the authorization flow itself — it only advertises where to find it and enforces that a request carries a token:
it serves
GET /.well-known/oauth-protected-resource(RFC 9728), and the same content again under/.well-known/oauth-protected-resource/mcp(the resource-scoped path the MCP spec also has clients try), both with open CORS and naming the BriefGate API as the authorization server — seeBRIEFGATE_MCP_AUTH_SERVERabove;every MCP request now needs a Bearer token — including
initializeandtools/list, which used to work without one so a registry could introspect the tool list. One with no token gets HTTP401and aWWW-Authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource"header, which is the signal an OAuth client uses to start signing in;if a tool call's key turns out to be expired or revoked (the API answers
401), the response is rewritten into a real HTTP401with the same header pluserror="invalid_token", rather than an ordinary tool error — so the client knows to refresh rather than just reporting the call failed.
What a connecting client actually does, against the authorization server named
in that metadata: standard OAuth 2.1 discovery
(GET /.well-known/oauth-authorization-server), dynamic client registration
(POST /v1/oauth/register), then an authorization-code exchange with PKCE
(S256) at POST /v1/oauth/token — no client secret, since MCP clients are
public clients — and POST /v1/oauth/revoke to end a session. None of that is
this package's concern; it only has to be a correct resource server pointing
at it. The access token that comes out the other end is a bg_live_... key
like any other, with a one-hour expiry the API enforces.
None of this applies without BRIEFGATE_MCP_PUBLIC_HOST: a local --http run
keeps behaving exactly as before, including an absent key reaching
initialize/tools/list and a plain Authorization: Bearer ... header
working with no OAuth involved.
Tools
define_intake
Create a new client intake — a branded portal where the client submits the assets you need. BriefGate sends the invite email and chases the client automatically until everything is collected.
project_name: "Website for John Finance"
client: { email: "john@example.com", name: "John", language: "cs" }
// also_notify: [{ email: "jane@example.com", name: "Jane" }]
// Others at the client who get the same link and the same reminders — either of
// them can supply the material. Each gets their own email; nobody sees the rest.
due_date: "2026-08-15"
branding: { accent_color: "#1B2A4A", sender_name: "Radim" }
// Custom branding (Solo plan and up). On Free these are stored but not used: the
// email and portal show a built-in sender name with the account owner's address.
chase_schedule: "default" // default | gentle | aggressive | custom | off
// chase_interval: 5, chase_interval_unit: "minutes" // only with "custom"; omit for every 3 days
// respect_quiet_hours: false, max_reminders: 12 // for a deliberately rapid cadence
items:
- { key: "logo", type: "image", label: "Company logo",
constraints: { formats: ["svg","png"], min_width: 512 } }
- { key: "hero_copy", type: "longtext", label: "Homepage headline",
constraints: { max_chars: 400 } }
- { key: "brand_colors", type: "color_list", label: "Brand colors", required: false }
- { key: "ga4_id", type: "text", label: "Google Analytics ID",
pattern: "^G-[A-Z0-9]+$", required: false }
- { key: "wp_admin", type: "secret", label: "WordPress admin credentials" }
- { key: "photos", type: "file_list", label: "Photos (5–10 images)",
constraints: { formats: ["jpg","png","heic"], min_count: 5, max_count: 15 } }
- { key: "opening_hours", type: "structured", label: "Opening hours",
schema: { type: "object", properties: { mon_fri: { type: "string" }, sat: { type: "string" } } } }
- { key: "has_existing_site", type: "boolean", label: "Does the client have an existing website?" }
- { key: "website_url", type: "url", label: "Current website URL", required: false }
- { key: "service_tier", type: "select", label: "Service package",
options: [{ value: "basic", label: "Basic" }, { value: "pro", label: "Pro" }] }
// folder_id: "fld_1"
// Put the intake straight into an existing folder from list_folders instead
// of leaving it unfiled.
// client_brief: "Here's the offer we agreed on, plus a few notes on scope..."
// Free text shown to the client above the requested items — information from
// you to them, not another thing you're asking them for. Up to 5000 characters.
// Documents go through POST /v1/intakes/:id/brief/files (dashboard or REST,
// not through MCP).Item key rules: must be snake_case (e.g. logo, hero_copy, ga4_id). Keys become property names in get_intake_results — no uppercase, no spaces, no hyphens.
Returns { intake_id, portal_url, status }. Save intake_id for all follow-up calls.
get_intake_status
Check which items are submitted, pending, or need revision. Includes the history of automated chase emails and when the client last opened the portal.
intake_id: "in_8f3k"Returns per-item status and a full chase history.
get_intake_results
Retrieve typed submitted values. Files are signed URLs (valid 24 hours). Secrets are one-time — decrypted and returned on the first call only; store them before moving on.
intake_id: "in_8f3k"
only_new: true // only items new since last call
include_pending: false // omit unsubmitted itemsReturns { results: { logo: "https://signed...", hero_copy: "text...", wp_admin: "s3cr3t" }, meta: { ... } }.
request_revision
Ask the client to resubmit an item with a note explaining what is wrong.
intake_id: "in_8f3k"
item_key: "logo"
note: "Logo is blurry — we need at least 512 px wide in SVG or PNG with a transparent background"Returns { status: "revision_requested", item_key }.
send_chase
Send a manual reminder outside the automatic schedule. Use when a deadline is approaching or email attempts have failed.
intake_id: "in_8f3k"Returns { sent: true }.
list_intakes
List all intakes across projects, optionally filtered by status, client email, folder, or a text search.
status: "in_progress" // draft | sent | in_progress | completed | archived
client_email: "john@example.com"
folder_id: "fld_1" // or "none" for intakes not in any folder
q: "Finance" // substring match on project name, client name, or client email
limit: 20
offset: 0Returns { intakes: [...], total }.
add_items
Add new items to an already-sent intake — for example a favicon you forgot, or additional credentials needed mid-project.
intake_id: "in_8f3k"
items:
- { key: "favicon", type: "image", label: "Favicon (32×32 PNG or ICO)" }Returns the updated intake.
update_item
Change an item's definition after the intake was sent — the type, label, help text or constraints. Use this when you asked for the wrong thing, e.g. you requested an image but the client has a PDF.
intake_id: "in_8f3k"
item_key: "logo"
type: "file" // was "image"
constraints: { formats: ["pdf","ai","svg"] }
discard_submitted_value: false // true is required if the change invalidates what the client already sentReturns the updated item. If the client already submitted a value that the new definition would reject, the call fails with item_answer_would_be_discarded until you pass discard_submitted_value: true.
update_intake
Change settings on an already-sent intake — project name, due date, reminder cadence, quiet hours, the client brief, or the client's name, phone, language, and timezone. Use this instead of deleting and recreating the intake, which would re-send the invite.
intake_id: "in_8f3k"
due_date: "2026-12-01"
chase_schedule: "gentle" // was "default"
max_reminders: "unlimited" // reactivates a stalled intake if it had hit its cap
// folder_id: "fld_1" // move it into a folder; null removes it from any folder
// client_brief: "Updated offer..." // replaces the brief shown above the items; null clears itIf any chase-related field changes (chase_schedule, chase_interval, chase_interval_unit, chase_at_time, max_reminders, respect_quiet_hours, due_date, client.timezone) on a sent intake, every pending reminder is cancelled and re-planned from now — reminders already sent still count toward max_reminders. folder_id never touches the chase schedule.
The client's e-mail address cannot be changed here — the portal link and login are bound to it. Use manage_recipients for that. Fails if the intake is archived. Returns the full, updated intake object.
manage_recipients
Add, remove, or reinstate a person who receives an intake's invite and reminders, alongside or instead of the primary client.
intake_id: "in_8f3k"
action: "reinstate" // add | remove | reinstate
email: "extra@example.com"
name: "Petr" // only used with action="add"action="add" invites another address the same way also_notify does at define_intake time. action="remove" stops future reminders to that address. action="reinstate" is for a bounce that was wrong — the person did get the e-mail — it clears the bounce flag so reminders resume, and re-plans the chase schedule from now if that address was the only one still being chased.
manage_webhook
Register, list or remove a webhook endpoint so events are pushed to your service instead of you polling.
action: "create" // create | list | delete
url: "https://your.service/hooks/briefgate"
events: ["intake.completed", "intake.overdue"]
format: "raw" // raw | slack | discordaction: "create" returns a secret once — store it, it verifies every delivery signature and cannot be retrieved again. Remove with action: "delete" and webhook_id.
Because an agent receives the secret in a tool result, it can come to rest wherever that conversation is stored. There is no rotation endpoint: if a transcript leaks, delete the endpoint and create a new one to get a fresh secret.
Only register an endpoint you can actually receive on. An agent running in a terminal has no public HTTPS address; for that case register nothing and check on a schedule instead (see below).
list_folders
List the folders in your account, used to group intakes by client or project. Takes no arguments.
Call this before create_folder or before setting folder_id on define_intake, update_intake, or list_intakes — reuse an existing folder for a returning client instead of creating a duplicate.
Returns { folders: [{ id, name, sort_order, intake_count, created_at }] }.
create_folder
Create a new folder to group intakes, e.g. one per client.
name: "Acme Inc"Call list_folders first and reuse a matching folder — only create one when none of the existing folders fits. Fails with folder_exists if a folder with this name already exists. Returns the created folder.
login
Sign in without an API key — see Sign in without an API key. Takes no arguments.
Call it whenever another tool reports "Not signed in" or that the stored key was revoked or expired. The first call starts a device-authorization flow and returns a URL and a short code immediately; call it again (any time) to check whether it's been approved yet. Has no effect — it says so instead — if --api-key or BRIEFGATE_API_KEY already supplies a key. Not available on the hosted endpoint. Same flow as running npx @briefgate/mcp login from a terminal (which blocks until approved instead of needing a second call) — see Sign in without an API key.
logout
Removes the API key login stored locally for this BriefGate server, and best-effort revokes it on the server too. Takes no arguments.
If the revoke call fails — no network, the API unreachable — the local copy is still removed; the response says so and points at the BriefGate dashboard to revoke it there instead. Not available on the hosted endpoint. Same effect as running npx @briefgate/mcp logout from a terminal — see Sign in without an API key.
Decisions — questions for the developer
An agent building something hits things only the account holder can settle: does the discounted plan cost $19 or $29? Stopping to wait wastes the run; picking silently buries the assumption. A decision is the third option — pose the question, record the answer you are proceeding on, keep building.
{ "key": "discount_price", "type": "select", "assignee": "owner",
"label": "What does the discounted subscription cost?",
"options": [ { "value": "19", "label": "$19/month" },
{ "value": "29", "label": "$29/month" } ],
"proposed": { "value": "19", "rationale": "matches the competitor we benchmarked" } }type: "multiselect" takes several answers, bounded by constraints.min_count / max_count.
The proposal is stored apart from the real answer, so it can never be mistaken for one the developer gave — and it survives being overruled, which is the point: in three months you can still see that $19 was assumed, not agreed. Read it back from get_intake_results:
"results": { "discount_price": "19" },
"meta": { "discount_price": { "decided_by": "agent_proposal", "proposed_value": "19" } }decided_by is "owner" once a person has settled it and "agent_proposal" while it is still your own pick. A proposed decision comes back even without include_pending — you need the assumption you are building on. It does not bump revision, so an only_new read surfaces exactly the decisions someone has since answered.
You cannot answer your own question. The answer endpoint takes a dashboard session, not an API key: if the agent could confirm its own proposal and have it recorded as the developer's, the distinction would be worth nothing. Decisions are answered in the BriefGate dashboard.
Owner items never reach the client portal, never appear in a reminder, and never hold up completion — the intake is finished when the client is finished.
Knowing when the client is done
Nothing pushes to an MCP client on its own — MCP is request/response, so the server cannot wake your agent when the client finishes. define_intake therefore returns a follow_up block naming the mechanism that fits your setup:
"follow_up": {
"recommended": "schedule", // or "webhook" when an endpoint already exists
"webhook": { "active_endpoints": 0, "events": ["intake.completed", "item.submitted"],
"register_with": "manage_webhook" },
"schedule": { "check_with": "get_intake_status", "every_hours": 24,
"until": "2026-10-01T08:00:00.000Z" }
}You run a service → register a webhook with
manage_webhookand act onintake.completed.You are an agent in a terminal → set up a recurring check that calls
get_intake_statuseveryevery_hourshours untiluntil. A cron entry, a systemd timer, or your agent host's own scheduler all work.
Events worth acting on: intake.completed (everything is in) and intake.overdue (the deadline passed with required items missing — the project is blocked and the client needs a human, not another reminder).
The cadence tightens near the deadline (24h normally, 12h inside a week, 6h inside two days) and is not tied to the reminder schedule: a client can submit everything at 2am having never opened a reminder.
End-to-end example
# System prompt excerpt
You are a web development agent. When you need client assets:
1. Call define_intake with all assets needed for this project.
Use type=secret for passwords/credentials.
The chase engine runs automatically — do not poll more often than once per day.
2. Read follow_up in the response and set up how you will hear back:
register a webhook with manage_webhook if you have an HTTPS endpoint,
otherwise schedule a get_intake_status check at follow_up.schedule.every_hours.
3. When intake.completed arrives (or the scheduled check reports "completed"),
call get_intake_results. Download file URLs within 24 hours.
Secrets are shown only on the first retrieval.
4. If a submitted asset does not meet requirements (blurry logo, broken URL),
call request_revision with a clear note for the client.
If the client has the asset in another form, call update_item to change the type.
5. If the client is still unresponsive after 9 days, call send_chase for an
extra nudge outside the automatic schedule, or tell the developer the intake
is stuck and let them pick up the phone.Verifying webhooks
BriefGate signs every webhook with HMAC-SHA256 to prevent forgery and replay attacks. The @briefgate/mcp package exports a ready-made helper:
import { verifyWebhookSignature, parseWebhookEvent } from "@briefgate/mcp/webhook";The signature lives in the X-BriefGate-Signature header as t=<unix>,v1=<hex>:
Fastify (recommended)
import Fastify from "fastify";
import { verifyWebhookSignature, parseWebhookEvent } from "@briefgate/mcp/webhook";
const app = Fastify();
// Parse body as raw string — JSON-parsing before verification breaks the HMAC.
app.addContentTypeParser("application/json", { parseAs: "string" }, (req, body, done) => {
done(null, body);
});
app.post("/briefgate/webhook", (request, reply) => {
const rawBody = request.body as string;
const ok = verifyWebhookSignature(
process.env.BRIEFGATE_WEBHOOK_SECRET!,
request.headers["x-briefgate-signature"] as string,
rawBody,
// { toleranceSec: 300 } ← default; increase for slow networks
);
if (!ok) {
return reply.status(401).send({ error: "Invalid signature" });
}
const event = parseWebhookEvent(rawBody);
console.log("BriefGate event:", event.event, event.intake_id);
reply.send({ ok: true });
});Express
import express from "express";
import { verifyWebhookSignature, parseWebhookEvent } from "@briefgate/mcp/webhook";
const app = express();
// raw body parser — must come before express.json()
app.post(
"/briefgate/webhook",
express.raw({ type: "application/json" }),
(req, res) => {
const rawBody = Buffer.isBuffer(req.body)
? req.body.toString("utf8")
: String(req.body);
const ok = verifyWebhookSignature(
process.env.BRIEFGATE_WEBHOOK_SECRET!,
req.headers["x-briefgate-signature"] as string,
rawBody,
);
if (!ok) return res.status(401).json({ error: "Invalid signature" });
const event = parseWebhookEvent(rawBody);
console.log("BriefGate event:", event.event, event.intake_id);
res.sendStatus(200);
},
);Webhook events
Event | When | Key fields |
| Client submits an item |
|
| All required items approved | — |
| Client opens the portal |
|
| A reminder bounced |
|
| 3 reminders sent, no response |
|
Pricing
Free | Solo — $29/mo | Agency — $79/mo | |
Active intakes | 1 | 15 | 60 |
Items per intake | 10 | unlimited | unlimited |
Storage | 1 GB | 25 GB | 100 GB |
Invitations per day | 10 | no daily limit | no daily limit |
Branding | "powered by", built-in sender name | sender name, email wording, logo + colors | + custom sending domain |
Chase | email, default | email, all schedules | email, all schedules |
Secrets vault | — | yes | yes |
Webhooks + REST + MCP | yes | yes | yes |
Full pricing at GET https://api.briefgate.dev/pricing.json (no auth required — agents can read it directly).
Data residency
BriefGate is hosted in the EU: application servers at netcup GmbH in Nuremberg, Germany; files in Cloudflare R2 under EU jurisdiction. See the GDPR notes and the DPA.
Privacy Policy
This package is a thin client: it holds no data of its own and sends nothing
anywhere except to the BriefGate API at api.briefgate.dev, using the API key
you configure. It writes no telemetry and no analytics.
What BriefGate itself collects, how long it keeps it, who it is shared with and how to have it deleted is covered in full here:
Privacy Policy — https://briefgate.dev/docs/privacy
Security — https://briefgate.dev/docs/security
Data Processing Agreement — https://briefgate.dev/docs/dpa
Contact for privacy requests: privacy@briefgate.dev
MCPB bundle (Claude Desktop Extension)
manifest.json at the repo root packages the local
@briefgate/mcp package as a one-click Claude Desktop install
(MCPB spec). It runs dist/index.js
locally and prompts for an optional API key at install time — the same
login/BRIEFGATE_API_KEY setup documented above, not the hosted
endpoint's OAuth flow.
Build the bundle (production dependencies only, packed in a throwaway
staging directory so it never touches this repo's own node_modules):
npm run package:mcpbThis produces briefgate.mcpb at the repo root (gitignored — install it
locally to test, don't commit it). Not yet submitted anywhere; see
scripts/build-mcpb.mjs for what the command does.
Contributing
This repository is the BriefGate MCP client only — a thin wrapper over the public BriefGate REST API. The BriefGate service itself is closed source.
npm install
npm run typecheck # TypeScript check
npm run lint # ESLint
npm run test # Vitest
npm run check # all three
npm run build # compile to dist/License
MIT — use freely in commercial projects.
Made by Radim Sekera. Related project: impri.dev — human-in-the-loop approval inbox for AI agents.
Available Tools
15 toolsadd_itemsAdd items to an intakeAInspect
Add new items to an already-sent intake — for example, when you realise mid-project that you also need a favicon, social media assets, or additional credentials.
The client is notified about the new items. Existing items and their submitted values are not affected. Returns the updated intake object.
Items must follow the same key/type/label rules as define_intake (snake_case keys, type-specific constraints).
Inputs: items (required), intake_id (required). Returns: items, status, folder_id, follow_up, +2 more
create_folderCreate a folderAInspect
Create a new folder to group intakes, e.g. one per client.
Call list_folders first and reuse a matching folder — only create one when none of the existing folders fits. Fails with folder_exists if a folder with this name already exists; use list_folders to find it instead.
Returns the created folder { id, name, sort_order, intake_count, created_at }.
Inputs: name (required). Returns: id, name, created_at, sort_order, +1 more
define_intakeCreate client intakeAIdempotentInspect
Create a new client intake request — a branded portal where the client submits logos, copy, files, credentials, and other assets. BriefGate sends the invite email and chases the client automatically until all items are collected.
Call this once at the start of a project, after you know what assets you need. Returns { intake_id, portal_url, status, follow_up }. Save intake_id — you need it for all follow-up calls.
The server cannot notify this conversation when the client finishes (MCP is request/response), so the returned follow_up block describes how completion will be learned:
follow_up.recommended = "webhook" — the account has an active webhook endpoint; completion events are delivered there.
follow_up.recommended = "schedule" — no endpoint is registered. follow_up.schedule gives the cadence for checking with get_intake_status (every_hours) and the date to stop (until). An account that runs a public HTTPS service can register an endpoint with manage_webhook instead.
Example: { "project_name": "Website for John Finance", "client": { "email": "john@example.com", "name": "John", "language": "cs" }, "due_date": "2026-08-15", "branding": { "accent_color": "#1B2A4A", "sender_name": "Radim" }, "items": [ { "key": "logo", "type": "image", "label": "Company logo", "constraints": { "formats": ["svg","png"], "min_width": 512 } }, { "key": "hero_copy", "type": "longtext", "label": "Homepage headline (2–3 sentences)", "constraints": { "max_chars": 400 } }, { "key": "wp_admin", "type": "secret", "label": "WordPress admin credentials" }, { "key": "photos", "type": "file_list", "label": "Photos (5–10 images)", "constraints": { "formats": ["jpg","png","heic"], "min_count": 5, "max_count": 15 } } ] }
Item types: text, longtext, file, file_list, image, color_list, select (one of options[]), multiselect (several of options[]; min_count/max_count in constraints), boolean, url, secret (encrypted; the value is shown only on the first retrieval), structured (requires schema with JSON Schema).
DECISIONS — questions for the account holder, not the client. An item with assignee="owner" and type select/multiselect is a question only the account holder can answer ("does the discounted plan cost 19 or 29?"). It can carry an optional "proposed" answer, e.g. proposed = { value: "19", rationale: "matches the competitor we benchmarked" }, which is stored separately from the account holder's answer and clearly labelled as a proposal.
get_intake_results returns the current answer with meta..decided_by: "owner" when the account holder answered in the dashboard, "agent_proposal" while only the proposal exists. A proposal cannot be confirmed through this API; only the account holder answers it. Item keys must be snake_case (e.g. "logo", "hero_copy", "ga4_id") — they become property names in get_intake_results.
Inputs: items (required), client (required), project_name (required), send, +14 more. Returns: status, notices, follow_up, intake_id, +1 more
get_intake_resultsCollect intake resultsADestructiveInspect
Retrieve the typed submitted values from a client intake.
Files are returned as signed download URLs that expire after 24 hours.
Secrets (type=secret, e.g. passwords, API keys) are decrypted and included only in the first retrieval. Later calls return first_reveal: false in meta and omit the value, so the user should be ready to receive a secret before this tool is called on an intake that contains one.
Use only_new=true to get only items submitted since the last call (useful in webhook-driven workflows). Use include_pending=true to also return partially filled items.
Returns { results: { : }, meta: { : { type, status, submitted_at, first_reveal? } } }.
For a DECISION item (assignee=owner, type select/multiselect), results holds the current answer and meta..decided_by is "owner" (answered by the account holder) or "agent_proposal" (only a proposal exists). Proposals are returned even without include_pending. A proposal does not bump revision, so only_new returns decisions the account holder has answered or changed since the last call.
Inputs: intake_id (required), only_new, include_pending. Returns: meta, status, results, intake_id
get_intake_statusCheck intake progressARead-onlyIdempotentInspect
Check the completion status of a client intake — which items are submitted, pending, or need revision; the history of automated chase emails sent; and when the client last opened the portal.
Use this to decide whether to send a manual reminder (send_chase), request a revision (request_revision), or fetch results (get_intake_results). Returns per-item status and chase history.
This is also the call a scheduled check should make when no webhook is registered — see follow_up in the define_intake response for the cadence. When status becomes "completed", fetch the results with get_intake_results and carry on with the work that was waiting on them.
Inputs: intake_id (required). Returns: items, chases, status, due_date, +4 more
list_foldersList foldersARead-onlyIdempotentInspect
List the folders in your account, used to group intakes by client or project.
Call this before create_folder or before setting folder_id on define_intake, update_intake, or list_intakes — reuse an existing folder for a returning client instead of creating a duplicate.
Returns { folders: [{ id, name, sort_order, intake_count, created_at }] }.
Inputs: no named parameters. Returns: folders
list_intakesList intakesARead-onlyIdempotentInspect
List all intakes in your account, optionally filtered by status, client email, folder, or a text search.
Use this to get an overview of active projects, find a specific intake by the client's email when you have lost the intake_id, check how many intakes are currently in progress, or see what's in a folder from list_folders.
Returns { intakes: [...], total } where each intake includes intake_id, project_name, status, created_at, due_date, folder_id, and portal_url.
Inputs: q, limit, offset, status, +2 more. Returns: total, intakes
loginSign in to BriefGateAInspect
Sign in without pasting an API key, the same way snyk_auth works: this opens a browser page where a human approves this device, then stores the issued key locally.
Call this whenever a tool reports "Not signed in" or that the stored key was revoked or expired.
This is a TWO-PHASE tool because approval can take minutes — longer than a single tool call should block for:
The first call starts the sign-in and returns immediately with a URL and a short code (e.g. "WDJB-MJHT"). Tell the user to open the URL and confirm the code; a browser is also opened automatically when possible.
Call
loginagain (no arguments change) to check progress. While the human hasn't approved yet, it replies that it's still waiting. Once approved, the same call reports success and the key is saved — no further action needed, other tools start working immediately.
Do not wait silently for minutes on one call — call this tool again after telling the user to approve, and again if they say they've clicked Allow.
Has no effect if a key is already supplied via the --api-key flag or the BRIEFGATE_API_KEY environment variable — those always take priority over a locally stored one, so this tool says so instead of running the flow. Not available when this server is running as the shared hosted endpoint (mcp.briefgate.dev): there, connecting a client already triggers OAuth automatically.
Inputs: no named parameters.
logoutSign out of BriefGateADestructiveIdempotentInspect
Remove the API key login stored locally for this BriefGate server, and best-effort revoke it on the server too (a DELETE /v1/keys/current call using that same key). If the revoke call fails — no network, the API is unreachable — the local copy is still removed; the response says so and points at the BriefGate dashboard to revoke it there instead. Not available when this server is running as the shared hosted endpoint.
Inputs: no named parameters.
manage_recipientsManage intake recipientsADestructiveInspect
Add, remove, or reinstate a person who receives an intake's invite and reminders, alongside or instead of the primary client.
action="add" invites another address the same way also_notify does at define_intake time — its own message, its own bounce state; pass name to address it by name. action="remove" stops future reminders to that address. action="reinstate" is for a bounce that was wrong — the person did get the e-mail — and clears the bounce flag so reminders resume; if that address was the only one still being chased, the schedule is re-planned from now.
Fails if the address is not on the intake, or — for reinstate — if it never bounced in the first place.
Inputs: email (required), action (required), intake_id (required), name. Returns: object
manage_webhookManage webhook endpointsADestructiveInspect
Register, list, or remove a webhook endpoint: a public HTTPS URL on the user's own service that BriefGate POSTs intake events to, as an alternative to polling get_intake_status. Webhook reference: https://briefgate.dev/docs/webhooks
The endpoint must be reachable from the internet over HTTPS. A URL that cannot receive (for example a process that runs only in a local terminal) produces failing deliveries while the intake looks watched, so without such a service polling get_intake_status is the working option.
action="create" returns a signing "secret" exactly once. The receiving service needs it to verify the signature on every delivery (verifyWebhookSignature from @briefgate/mcp/webhook), and it cannot be shown again. If it is ever exposed, there is no rotation in place — delete the endpoint and create a new one, which issues a fresh secret.
Events: intake.completed (all required items in — the one to act on), item.submitted (a single item arrived), client.viewed (the client opened the portal), chase.bounced (a reminder failed to deliver), intake.overdue (the due date passed with required items outstanding — the one to act on when work is blocked), intake.stalled (fires only when the intake sets max_reminders; without it this event never arrives).
Inputs: action (required), url, events, format, +1 more. Returns: object
request_revisionRequest a revisionAInspect
Ask the client to resubmit a specific item with a note explaining what is wrong.
Use this after reviewing get_intake_results and finding an item that does not meet requirements — for example a blurry logo, copy that is too long, or a broken URL. The client is notified automatically and the item status moves to needs_revision.
Returns { status: "revision_requested", item_key }.
Inputs: note (required), item_key (required), intake_id (required). Returns: status, item_key
send_chaseSend a reminderAInspect
Send a manual reminder to the client outside the automatic schedule.
Use when a deadline is approaching and the client has not responded to automatic reminders, or when you want to send an SMS after email attempts have failed. The automatic chase schedule continues after this call — this is an extra nudge, not a replacement.
Returns { sent: true }.
Inputs: intake_id (required), channel. Returns: sent
update_intakeEdit intake settingsAInspect
Change settings on an intake that has already been sent — project name, due date, reminder cadence, quiet hours, which folder it's in, the client brief, or the client's name, phone, language, and timezone.
Use this instead of deleting and recreating the intake when a deadline moves or the chase cadence needs to change. If any of chase_schedule, chase_interval, chase_interval_unit, chase_at_time, max_reminders, respect_quiet_hours, due_date, or client.timezone is included, every pending reminder is cancelled and the schedule is re-planned from now — reminders already sent still count toward max_reminders. Raising max_reminders (or setting it to "unlimited") past the number already sent on a stalled intake reactivates it and resumes chasing.
The client's e-mail address cannot be changed here — the portal link and login are bound to it. Use manage_recipients to add, remove, or reinstate an address.
folder_id moves the intake to a different folder (an id from list_folders); set it to null to remove the intake from any folder. It never touches the chase schedule.
client_brief replaces the free-text brief shown to the client above the requested items; set it to null to clear it. Documents attached to the brief are managed via the dashboard or the REST endpoint POST /v1/intakes/:id/brief/files, not through this tool.
Fails if the intake is archived. At least one field must be given. Returns the full, updated intake object.
Inputs: intake_id (required), client, due_date, folder_id, +9 more. Returns: object
update_itemEdit an itemADestructiveInspect
Change one item on an intake that is already with the client — its type, label, hint, whether it is required, and which file formats it accepts.
Reach for this when the field turns out to be the wrong shape: you asked for an image and the client only has their logo as a PDF, or what you asked for as a line of text is really a file. Widening the accepted formats or switching the type unblocks them without adding a duplicate item and waiving the original.
The item key cannot be changed — results come back under it, so renaming would break whatever reads them. Add a new item instead.
If the client has already answered and the change would make their answer invalid, the call fails and nothing is touched. Repeat it with discard_submitted_value: true to clear the answer and ask them again. A change that leaves their answer valid (a new label, a wider limit) never discards anything.
Inputs: item_key (required), intake_id (required), help, type, +6 more. Returns: item, discarded_submitted_value
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools have clearly distinct purposes tied to specific resources (intake status vs results, add_items vs update_item vs update_intake), and transitions are documented. Minor potential confusion between get_intake_status and get_intake_results, and the two generic 'manage_*' tools, but descriptions resolve these well.
Predominantly consistent snake_case verb_noun pattern (define_intake, list_intakes, update_item, request_revision, create_folder). Deviations are minor: login/logout lack a noun, and verbs vary slightly (define_ vs create_, get_ vs list_) though usage is intuitive.
15 tools is well-scoped for a client-intake lifecycle product; each tool maps to a distinct operation (intake CRUD, items, recipients, folders, webhooks, auth) with no filler.
Strong lifecycle coverage: create, list, update, status, results, revisions, chases, recipients, folders, webhooks, auth. Minor gaps remain — no archive/delete intake tool (archive state is referenced but not settable) and no remove-item operation, and owner decisions cannot be answered via API.
Maintenance
Related MCP Connectors
Send encrypted files and secrets, collect files and get documents signed, from your AI.
Create documents and reusable templates, request signatures, and track approvals — for AI agents.
A design agent in your coding agent's loop: briefs each screen, reviews UX and visual quality.
Let your AI agent build, preview and update web apps, download source and publish when you allow it.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI coding agents to plan, build, and review websites and product interfaces with a persistent, user-led process, including design direction, component contracts, and implementation review.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to vet a developer's shipped products, check fixed pricing and availability, and submit project briefs on behalf of users.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to create client-editable photo and video galleries, upload and organize media in bulk, generate embed code for popular site builders, and manage client feedback — so non-technical clients can update their own content without a CMS.67 npm1MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to publish work mid-task and request review from real human reviewers, who return pinned comments anchored to the exact elements that are off along with an approval verdict. The agent then iterates on that human feedback until the work is approved, keeping users out of the revision loop.38 npmMIT