# Using the Briefs MCP Server

Operational guide for connecting an AI agent to Briefs over MCP, and what becomes possible
once connected. For the concept of Briefs, see https://sharebriefs.com/brief/intro. For
authentication specifics (OAuth vs personal access tokens), see
https://sharebriefs.com/brief/authentication.

## What it is

Briefs exposes a remote MCP server at:

```
https://mcp.sharebriefs.com
```

It speaks MCP over streamable HTTP (a single POST endpoint). Connecting gives an agent tools
to create, read, update, share, and organize Briefs and Pages, plus manage organizations,
members, and invitations — the same capabilities described across the other Briefs in this
set.

Reading a public Brief never requires the MCP — any agent can fetch its URL. The MCP is for
authenticated actions: working with private or internal content, and creating or managing
content on the user's behalf.

## Connecting

The server uses OAuth, so most clients walk the user through a browser sign-in on first use —
no manual key handling for interactive clients.

- **Claude Code (CLI):**
  ```
  claude mcp add --transport http sharebriefs https://mcp.sharebriefs.com
  ```
  Then run `/mcp` and choose Authenticate to complete the OAuth sign-in.

- **Claude Desktop / Claude web:** Add a custom connector and enter the URL
  `https://mcp.sharebriefs.com`. You'll be taken through Briefs sign-in and a consent screen.

- **Other MCP clients:** Point the client at `https://mcp.sharebriefs.com` as a
  streamable-HTTP MCP server. Clients that support OAuth discovery find the sign-in flow
  automatically; clients that take a bearer token can use a Personal Access Token instead
  (see Authentication below).

Use the bare host `https://mcp.sharebriefs.com`. Do not use `https://sharebriefs.com` (the
website) or append a path — OAuth discovery is served on the `mcp.` host, and pointing a
client at the wrong host fails during authentication.

## Authentication

Two ways to authenticate, both detailed in https://sharebriefs.com/brief/authentication:

- **OAuth (recommended for interactive clients).** Sign in through the browser and approve
  the requested permissions on the consent screen. This grants read and write access across
  Briefs, Pages, your profile, and organizations.
- **Personal Access Token (for headless or token-based clients).** Generate a token in your
  account settings and supply it as `Authorization: Bearer sb_...`. Tokens have full access.

## First-time setup: choose a username

Content is addressed as `username/name`, so an account needs a username before it can
create Briefs or Pages. If the user signs up while connecting the MCP, finish the prompted
onboarding step and choose a username. Until that is done, tools that create content (e.g.
`create_brief`, `create_page`) return an error directing the user to finish setup at
https://sharebriefs.com/onboarding. Reading and listing still work without a username.

## What you can do once connected

The server groups tools by area; fetch the linked Brief for operational detail:

- **Briefs** — `create_brief`, `get_brief`, `list_briefs` (own, or another owner via the
  `owner` param), `update_brief` (content, rename via `new_name`, and visibility),
  `delete_brief`, plus `like_brief` / `unlike_brief`. See
  https://sharebriefs.com/brief/managing and, for authoring,
  https://sharebriefs.com/brief/creating.
- **Pages** — host single-file HTML documents (dashboards, reports, charts, visuals) with
  the same owners and permissions as Briefs, viewed and shared at
  `sharebriefs.com/{owner}/pages/{name}`. Tools: `create_page`, `get_page`, `update_page`
  (content and visibility), `delete_page`, `list_pages`. See
  https://sharebriefs.com/brief/pages.
- **Sharing** — collaborators and permission levels (`read`/`write`/`admin`) on a single
  Brief or Page. Briefs: `list_collaborators`, `add_collaborator` (also updates an existing
  collaborator's permission, or sends an invitation if the user isn't one yet),
  `remove_collaborator`, `check_permission`, and `list_brief_invitations` /
  `update_brief_invitation` / `cancel_brief_invitation`. Pages have the direct equivalents:
  `list_page_collaborators`, `add_page_collaborator`, `remove_page_collaborator`. See
  https://sharebriefs.com/brief/sharing.
- **Organizations** — shared team namespaces, members, roles, and settings.
  `create_org`, `get_org`, `list_orgs`, `update_org` (settings, and **rename the org** via
  its `namespace` param), `delete_org`; members via `list_org_members`, `invite_to_org`,
  `update_org_member` (promote/demote between admin and member), `remove_org_member`,
  `leave_org`, and the org invitation tools. See
  https://sharebriefs.com/brief/organizations.
- **Enterprise SSO** — domain-verified single sign-on setup:
  `setup_company_sso`, `get_sso_status`, `get_sso_setup_link`, `disable_sso`. See
  https://sharebriefs.com/brief/enterprise.
- **Profile** — `get_profile` (your own) and `get_user` (look up a user by username), plus
  `update_profile` to **change your username** (this rewrites the URLs of all your Briefs and
  Pages — the old `username/...` links stop resolving, so confirm with the user first).

Tool names are snake_case (e.g. `create_brief`, `create_page`, `list_briefs`,
`add_collaborator`, `invite_to_org`). The exact names and parameters are surfaced by the MCP
client; this Brief set explains when and how to use them.

## Agent workflow

1. On a task, start from the index — https://sharebriefs.com/brief/index — and fetch
   the specific Brief for the job rather than loading everything.
2. Decide the content type: markdown knowledge → a Brief; a rendered/interactive HTML
   artifact → a Page (https://sharebriefs.com/brief/pages).
3. Before creating, list existing content for the target owner to avoid duplicates.
4. Prefer updating existing content over creating a new version; the URL is the stable
   contract.
5. Hand the user the canonical URL after any change. Confirm before destructive or
   URL-changing actions (delete, rename an org or username).

## Related Briefs

- Concept overview: https://sharebriefs.com/brief/intro
- Pages (hosted HTML): https://sharebriefs.com/brief/pages
- Authentication & tokens: https://sharebriefs.com/brief/authentication
- REST API (non-MCP access): https://sharebriefs.com/brief/api
- Managing Briefs: https://sharebriefs.com/brief/managing