# Knapsack

Knapsack delivers your design system to Claude Code, Cursor, and VS Code over the Model Context Protocol (MCP), and shows you what each agent received.

Two products run inside one app at https://knapsack.sh. **Context** turns the design system a workspace attaches (docs, Storybook, packages) into entities and serves them to agents over MCP. **Insights** holds the evidence of design system evals: whether that context made the agent's output better. Everything a person does in the app is an API operation an agent can call. Knapsack is in public beta and free until January 1, 2027.

## MCP servers

Both are Streamable HTTP, with OAuth sign-in or a workspace API key (see "API key").

**A workspace's context:** https://knapsack.sh/mcp/workspace/{workspaceId}

The URL to give a coding agent. It serves one workspace's design system: seven tools, the `build-ui` prompt, and each entity of the latest build as a resource. Five tools only read: `describe_context`, `search_context`, `read_context`, `check_usage` and `render_ui`. Two write: `remember` proposes a memory, which a workspace owner accepts or retires, and `send_feedback` files feedback with the Knapsack team and answers the identifier it was filed under (FB-12), which you give the user. `{workspaceId}` is the workspace's id (a uuid, not its slug): the app's Connect page shows the whole URL, and `listMyWorkspaces` on the setup server answers it.

**Setup:** https://knapsack.sh/mcp/manage

Sets up and manages every organization and workspace your person can open, as them: one tool per operation of the public API, named by its operationId. Organizations, workspaces, attachments (the design systems Context builds from), API keys (list, rename, revoke), memories, members (list), invitations, teams and tags. It reads no design system context. A tool that changes, replaces, deletes, retires or revokes something (every update, rename and delete), or sends an invitation, does nothing until your person agrees. A tool that adds runs at once, and a new version of an attachment, or a completed upload, replaces what that attachment serves without asking. What a person does in the app themselves is not there: creating an API key, changing members, team membership or ownership, join links, granting access, deleting an organization. An invitation you send, once your person agrees, can name a role and teams.

There is no account-wide or organization-wide MCP URL: `https://knapsack.sh/mcp` and `https://knapsack.sh/mcp/org/{organizationId}` answer `404`.

## Install

On first run, set up first, then connect the workspace:

1. If your person has no workspace with a synced attachment yet, add the setup server (below), or use Agent Auth (see "Sign up"), and create the organization, the workspace and its attachment.
2. Add the workspace's context server with its id, and build with it.

### The workspace's context server

Claude Code, then run `/mcp` in Claude Code and sign in:

```bash
claude mcp add --transport http --scope user knapsack_{org}_{ws} https://knapsack.sh/mcp/workspace/{workspaceId}
```

Cursor cannot sign in to Knapsack yet, so it sends a workspace API key from `KNAPSACK_API_KEY` (see "API key" below). Add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "knapsack_{org}_{ws}": {
      "url": "https://knapsack.sh/mcp/workspace/{workspaceId}",
      "headers": {
        "Authorization": "Bearer ${env:KNAPSACK_API_KEY}"
      }
    }
  }
}
```

VS Code, in the user `mcp.json` (MCP: Open User Configuration); it asks you to sign in when the server starts:

```json
code --add-mcp '{"name":"knapsack_{org}_{ws}","type":"http","url":"https://knapsack.sh/mcp/workspace/{workspaceId}"}'
```

Codex:

```bash
codex mcp add knapsack_{org}_{ws} --url https://knapsack.sh/mcp/workspace/{workspaceId}
codex mcp login knapsack_{org}_{ws}
```

Or every client `add-mcp` detects, in its global config. Cursor's entry then needs the API key header before it can connect:

```bash
npx add-mcp https://knapsack.sh/mcp/workspace/{workspaceId} --name knapsack_{org}_{ws} --global --yes
```

The workspace's Connect page in the app gives each client's steps with the real id and slugs filled in.

### The setup server

Claude Code, then run `/mcp` in Claude Code and sign in:

```bash
claude mcp add --transport http --scope user knapsack https://knapsack.sh/mcp/manage
```

VS Code, which asks you to sign in when the server starts: https://vscode.dev/redirect/mcp/install?name=knapsack&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fknapsack.sh%2Fmcp%2Fmanage%22%7D

Cursor, with a workspace API key in `KNAPSACK_API_KEY`, which reaches only the tools a key may call: cursor://anysphere.cursor-deeplink/mcp/install?name=knapsack&config=eyJ1cmwiOiJodHRwczovL2tuYXBzYWNrLnNoL21jcC9tYW5hZ2UiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgJHtlbnY6S05BUFNBQ0tfQVBJX0tFWX0ifX0%3D

Codex:

```bash
codex mcp add knapsack --url https://knapsack.sh/mcp/manage
codex mcp login knapsack
```

Or every client `add-mcp` detects:

```bash
npx add-mcp https://knapsack.sh/mcp/manage --name knapsack --global --yes
```

## Sign up

A Knapsack account needs a person: they verify their email address and approve what you may do. There are two ways in.

### From an MCP client (OAuth)

1. Install a server. Your client's first request answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://knapsack.sh/.well-known/oauth-protected-resource/mcp/manage"` (for a workspace URL, `…/oauth-protected-resource/mcp/workspace/{workspaceId}`). The authorization server is `https://knapsack.sh/api/auth`. Clients identify themselves with a Client ID Metadata Document; dynamic client registration is off.
2. The client opens your person's browser at sign-in. A person with no account chooses Create an account, then opens the verification link Knapsack emails them, in the same browser.
3. The consent page names your client and what the URL reaches. Your person chooses Allow, and the client gets a token bound to that URL, which it refreshes. A token for one URL is refused at every other.
4. On the setup server, your person creates an organization, a workspace and its first attachment through you, or in the app. Then connect that workspace's URL: until its attachment has synced, the context server has nothing to serve.

### Without an MCP client (Agent Auth)

1. Read https://knapsack.sh/.well-known/agent-configuration (the Agent Auth Protocol, a draft: delegated mode, device-authorization approval). Register with your own Ed25519 key, or let the Agent Auth CLI do it. Pass Knapsack's URL with `--url=`, in that form: without it the CLI looks Knapsack up in its directory and fails with "Direct discovery is disabled", and `--url` followed by a space takes the next word as a second URL.
   - As an MCP server (stdio), for an agent that speaks only MCP: `npx @auth/agent-cli@0.5.1 --url=https://knapsack.sh mcp`
   - From a shell: `npx @auth/agent-cli@0.5.1 --url=https://knapsack.sh connect --provider https://knapsack.sh --no-browser --capabilities getMe createOrganization createOrgWorkspace createAttachment createWorkspaceApiKey`. With `--no-browser` it prints the approval link (`Approval required. Open: …`) and polls until your person answers; without it, it opens a browser on your own machine and prints no link. `npx @auth/agent-cli@0.5.1 --url=https://knapsack.sh capabilities --provider https://knapsack.sh` lists the rest.
2. Ask for the capabilities you need and give your person the approval link, `https://knapsack.sh/agents/approve?agent_id=…&code=…`. It lasts five minutes, so tell your person to approve it now, not later. A person with no account signs up from it, verifies their email, and comes back to it; if it ran out meanwhile, ask again.
3. Your person chooses Approve. You then act as them, with their access, in what they approved: the operations in https://knapsack.sh/api/v1/openapi whose security lists `agentAuth` (among them `getMe`, `createOrganization`, `createOrgWorkspace`, `createAttachment` and `createWorkspaceApiKey`).
4. Issue the key with `createWorkspaceApiKey` from a shell, not from the CLI's MCP mode: there the answer, the key in it, lands in your context, so an agent that speaks only MCP holds no key: it adds the setup server as in From an MCP client above, which signs your person in, sets the attachment's source there, then connects the workspace's URL. The CLI prints the answer to stdout and the key is shown this once, so redirect the output to a file only you can read (mode 0600), a new one each time (`>` empties an existing file before the CLI runs): `umask 077; npx @auth/agent-cli@0.5.1 --url=https://knapsack.sh execute <agent-id> createWorkspaceApiKey --args '{"org":"<org>","ws":"<workspace>","body":{"name":"<name>"}}' > ks-key.json`, where <agent-id> is the `agentId` that `connect` prints once your person approves (the `agent_id` in the approval link). Read the key from that file; never print or echo it (the answer's `handling` says the same). Without `expiresAt` (1 to 365 days out) the key lapses in 30 days. An unknown field is a 400 that names it and the accepted ones.
5. With the key you created, set the attachment's source through the API. That key also reads the workspace's context at its MCP URL. Your person sees and revokes you under Connected apps in their account, which revokes your keys too.

## API key

A client that cannot sign in sends a workspace API key as its bearer: to the workspace's URL (its seven tools), to https://knapsack.sh/mcp/manage (the tools whose operations accept a key, scoped to the key's workspace: among them `listMyWorkspaces`, its attachments and their sync jobs, its keys, its memories and its tags), or to the API:

```http
Authorization: Bearer ${KNAPSACK_API_KEY}
```

A key reaches only the workspace it was created in. It is created from a signed-in session in the app or by an agent your person approved. Read it from the environment or a secret store. Never print it, commit it, or ask your person to paste it into a chat.

## Docs and API

- Docs for agents: https://knapsack.docs.buildwithfern.com/llms.txt (append `.md` to any docs page for its markdown)
- The MCP servers, in detail: https://knapsack.docs.buildwithfern.com/context/mcp.md
- OpenAPI document: https://knapsack.sh/api/v1/openapi
- API overview: https://knapsack.docs.buildwithfern.com/api-reference/overview.md

## Privacy, security and contact

- Privacy policy: https://www.knapsack.cloud/legal/privacy
- Privacy questions: privacy@knapsack.cloud
- Security: https://www.knapsack.cloud/legal/security
- Security questions, or a security issue to report: security@knapsack.cloud
- Anything else: help@knapsack.cloud