briefgate-mcp

# BriefGate

**Client intake for AI coding agents.**

Your agent can build the website.
BriefGate gets the missing things from the client.

```
Claude Code / Cursor / Codex → BriefGate → Client portal
  → Files · copy · credentials · structured data → Agent continues building
```

![BriefGate demo: an intake being defined, the client filling the portal, results coming back](https://briefgate.dev/assets/demo/killer-demo.gif)

[Watch as MP4 (25 s)](https://briefgate.dev/assets/demo/killer-demo.mp4) · [Full 47 s walkthrough](https://briefgate.dev/assets/demo/briefgate-demo.mp4)

[Website](https://briefgate.dev?utm_source=github&utm_medium=readme&utm_campaign=mcp_launch) · [MCP reference](https://briefgate.dev/docs/mcp) · [llms.txt](https://briefgate.dev/llms.txt) · [Guides and checklists](https://briefgate.dev/guides)

Not working with an agent? The same intakes can be created from the browser dashboard — see the [dashboard quickstart](https://briefgate.dev/docs/dashboard-quickstart).

## 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.

## Quickstart

**Claude Code — hosted, no key to manage:**

```bash
claude mcp add --transport http briefgate https://mcp.briefgate.dev/mcp
```

Then run `/mcp` in Claude Code, pick **briefgate**, and choose **Authenticate**.

**Claude Code — local package:**

```bash
claude mcp add briefgate -- npx -y @briefgate/mcp
npx -y @briefgate/mcp login
```

Prefer to skip sign-in entirely? Get a key at [briefgate.dev](https://briefgate.dev?utm_source=github&utm_medium=readme&utm_campaign=mcp_launch) (free tier, no card) and pass it as `BRIEFGATE_API_KEY`.

**Cursor** — add to `.cursor/mcp.json`:

```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:**

```bash
codex mcp add briefgate --env BRIEFGATE_API_KEY=bg_live_xxxxx -- npx -y @briefgate/mcp
```

**Gemini CLI** — installs as an extension from this repo's [`gemini-extension.json`](gemini-extension.json), pointed at the hosted endpoint:

```bash
gemini extensions install https://github.com/sekera-radim/briefgate-mcp
```

It authenticates the same way as the other hosted clients above — via OAuth, on first use. The extension also ships [`GEMINI.md`](GEMINI.md), a context file that tells the model what BriefGate is and when to reach for it.

**Claude Desktop** — one-click install as a [Desktop Extension](https://www.anthropic.com/engineering/desktop-extensions) (`.mcpb`), running the local `@briefgate/mcp` package instead of the hosted endpoint. Build details: see [MCPB bundle](#mcpb-bundle-claude-desktop-extension) below.

**Cursor** — as a [plugin](https://cursor.com/docs/plugins) from this repo's [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json), which bundles the same MCP config together with the `collect-from-client` skill below.

**Any [Agent Skills](https://agentskills.io)-compatible tool** (OpenAI Codex, GitHub Copilot / VS Code, Cursor, Gemini CLI, and other clients on that standard) — install the [`collect-from-client`](skills/collect-from-client/SKILL.md) skill with the [`skills` CLI](https://github.com/vercel-labs/skills):

```bash
npx skills add https://github.com/sekera-radim/briefgate-mcp/tree/main/skills/collect-from-client
```

The 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](#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`:

```markdown
## 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`:

```json
{
  "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](https://briefgate.dev?utm_source=github&utm_medium=readme&utm_campaign=mcp_launch).

## 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](https://briefgate.dev) (free tier available, no card required):

```bash
claude mcp add briefgate \
  -e BRIEFGATE_API_KEY=bg_live_... \
  -- npx -y @briefgate/mcp
```

Or add manually to `~/.claude/settings.json`:

```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:**

```bash
npx -y @briefgate/mcp login     # prints a code + URL, waits for approv