Docs MCP — setup & access

Connect your AI assistant — the Claude app or Claude Code — to the Works by Design HubSpot documentation, so it builds the way HubSpot is actually built. First-time setup takes roughly 10–15 minutes, much of it waiting for the sign-in email to arrive; when Claude Code or connector access is already in place, it's a minute or two. Access is limited to approved email addresses. For what it does and why, see the overview.

How access works: you add the server to your AI client, and the client walks you through a one-time OAuth sign-in in the browser — you confirm your approved work email and the client stores its own credential. There is no key to copy or paste, and on the recommended path there is no address to type either. If your email isn't approved yet, get in touch.

What you can read: every sign-in grants the HubSpot technical documentation. Depending on your access it can also include further documentation sets (business & sales-engineering context under business/, server infrastructure under webserver/) — docs_list shows exactly what yours includes.

Which setup is for you?#

Two different things are on offer here: the documentation, readable from every client below, and the demo skills — the ones that build demo pages and workspaces — which exist only in the Claude Code plugin.

Connect — Claude Code#

The full setup: the documentation and all the skills, including the demo skills. Six steps, done in order in one sitting — each one says exactly where to type.

Claude Code is a separate chat surface from your normal Claude conversation. It lives as a Claude Code tab inside the Claude desktop app, as a Claude Code panel in VS Code, and as a terminal tool for developers — all three share one configuration, so you set up once. Every /plugin and /mcp command on this page goes into Claude Code's chat input; typed into a regular Claude chat, they just send as ordinary messages.

1. Get Claude Code#

• You already use the Claude desktop app? Then you already have Claude Code — open the app's Claude Code tab. Nothing new to install.
• You work in VS Code? Install the Claude Code extension from the VS Code marketplace, then open its Claude Code panel.
• There is also a terminal CLI, but you don't need it for this setup — the whole plugin path happens inside Claude Code's own chat input, never a system terminal.

2. Add the marketplace#

Type /plugin on its own into Claude Code's chat input — the Claude Code tab in the desktop app, or the Claude Code panel in VS Code; not your regular Claude chat — and press Enter. The plugin manager opens (in VS Code, choose Manage plugins if a menu appears first). Open the Marketplaces tab, paste this address, and click Add:

https://worksby.design/git/plugins.git

3. Install the plugin#

In the same plugin manager, open the Plugins tab, scroll to worksbydesign, click Install (installing for you makes it yours in every project), and restart when asked. After the restart, type /plugin again and check that worksbydesign shows as installed and enabled — if it's listed but disabled, enable it.

That one install carries everything: quote-builder (customer quote PDF → live HubSpot quote) and demo-crm-data (realistic practice data in a portal) work with the standard technical access, and the six demo skills — deal-to-demo prep, demo pages, workspaces, customer context, brand capture and business case — come along in the same install, together with five helper subagents that do the heavy CRM and transcript reading and the page builds outside your conversation. Four things worth knowing about the demo skills:

• They are Claude-Code-only — the Claude app cannot run them.
• They use your own HubSpot CRM connection. "Prepare the demo for deal 123" reads the deal through the Internal HubSpot Connector your Claude organisation provides — step 6 connects it; without it the skill stops and tells you what to connect.
• They need the business-context documentation grant, but installing without it is harmless: the skills refuse politely and nothing breaks. Step 7 shows you how to check your grant.
• No folder setup is needed on your machine. The first time you ask for a demo workspace for a customer, the skill creates its own workspaces folder (default ~/demo-workspaces/<customer>/), reuses it from then on, and asks you if a choice is ever needed.

4. Sign in now#

Run /mcp in Claude Code's chat input and choose Authenticate next to worksbydesign (installed via the plugin it can be listed as plugin:worksbydesign:worksbydesign — same server). This opens the browser sign-in — your approved work email, a one-time emailed link, and a couple of clicks. The "You're connected" page at the end shows a copy-paste for your assistant — use it there and then; if you miss it, there's a fallback below.

If you skip this step, Claude Code prompts you the first time the documentation is used — the sign-in is the same either way.

5. Turn on auto-update#

Claude Code leaves auto-update off for marketplaces outside Anthropic's own — without it, new skills we publish never reach you. In a terminal-run Claude Code (type claude in a terminal; the setting is shared by every surface): run /plugin, open Marketplaces, choose worksby-design, and select Enable auto-update.

6. Connect your HubSpot CRM — demo skills only#

The demo skills read deals from the internal HubSpot CRM through one connector: the Internal HubSpot Connector that your Claude organisation provides. Connect it once and it is there in every folder. Skip this step if you only use the documentation, quote-builder or demo-crm-data.

1. In claude.ai open Settings → Connectors (claude.ai/customize/connectors), find the internal HubSpot connector and click Connect. Not listed there? It has not been enabled for you yet — ask your SE lead.
2. Back in Claude Code, run /mcp in the chat input. It appears as claude.ai Internal HubSpot Connector; if it says needs authentication, select it and authenticate. Then start a new session.

Connectors only show up when Claude Code is signed in with your claude.ai account — /status shows the login. They never appear under an API key.

Optional, same path: Glean, Fellow, Gmail and Google Calendar each make the deal brief fuller — internal documents, meeting notes, the email thread and the calendar with the customer. Gong call transcripts come with the HubSpot connector, nothing extra to connect. Step 7 reports which of these are connected.

Do not use a plain HubSpot connector for demo work: it is signed into a demo portal, and demo portals are only ever changed through the API or the CLI. The demo skills ignore it.

7. You're done — prove it#

Ask Claude Code — same chat input:

Check my worksby setup

That runs the setup-check skill: it verifies the connection, shows which documentation your sign-in includes, confirms every skill is present and current, and — if you build demos — offers to set up your demo workspaces folder. It asks before changing anything, and whatever is missing comes back as a short list with the exact fix. Building demos? The report should show business context in your access; if it doesn't, that grant is the thing to chase — get in touch.

That's the whole setup. Next time a deal needs a demo, ask Claude Code: Prepare the demo for deal 123 — it reads the deal, sets up the customer's workspace, syncs what's known, and comes back with a brief and the next steps to pick from.

claude mcp add --scope user --transport http worksbydesign https://mcp.worksby.design/

Connect — Claude app (documentation only)#

No terminal and nothing to install — but documentation only: the demo skills are not available here. Same on Windows and macOS, and in the browser.

1. In Claude, open Settings → Connectors.

2. Look for worksbydesign in the list. If it's there, click Connect and skip to the sign-in.

3. Otherwise click Add custom connector, give it any name you'll recognise (worksbydesign works), and paste this as the server URL:

   https://mcp.worksby.design/

4. Leave OAuth Client ID and Client Secret empty — the connector registers itself. Click Connect to start the browser sign-in.

Signing in#

The first time your client connects, it opens a Works by Design sign-in page in your browser. The flow is the same for every client:

1. Enter your approved work email. If it's approved, we email you a one-time link (valid 15 minutes); if it isn't, the page tells you straight away rather than leaving you waiting.
2. Click the link and press Complete sign-in on the page that opens. (The extra click is deliberate — it stops corporate email scanners from using up the one-time link before you do.) Your client stores its own per-install credential, so there is no key to copy.
3. A "You're connected" page appears with one final copy-paste, tailored to your access: paste it to your assistant and ask it to remember it permanently. That is what makes the documentation — and new skills — load from the start of every session. Then click Finish to return to your client.

Access is per person and per install: signing in again from the same client replaces that client's previous install, and each is logged under your address. Nothing is shown on screen to copy or share, and access can be revoked at any time.

First message to your assistant#

The "You're connected" page at the end of sign-in shows this same message tailored to your exact access — use that one if you can. Skipped it? Paste the version below once, into the assistant you just connected. Two reassurances first: the ~/.claude/CLAUDE.md path it mentions is a file your assistant creates and manages for itself — you never open or edit it. And the paste is safe wherever you use it: it asks the assistant to tell you exactly what to do if it cannot store persistent instructions, rather than failing silently.

Persist the following idempotently as global startup guidance in your supported
durable-instruction mechanism. For Claude Code, add or update it in
~/.claude/CLAUDE.md. Do not rely only on this conversation or on generated
memory, and do not create duplicate entries. Ensure the guidance is active in every new session and
remains governing across context compaction. If you cannot store or verify
persistent instructions, tell me exactly what I need to configure. After saving
it, confirm where it was stored.

You now have the "worksbydesign" MCP server, the authoritative Works by Design
HubSpot technical documentation.

Before answering any HubSpot question, call docs_get with "README.md" and use
its "Load when…" index to select the relevant documentation. Read each selected
file with docs_get. Use docs_search only when the index does not clearly identify
the right file or when locating a specific term. Ground your answer in the
retrieved documentation and cite its file paths.

If a file contains a verifiably incorrect or outdated statement, an important
omission, or a broken link, submit concise evidence through docs_feedback for
human review. Do not submit questions, opinions, duplicate reports, or
speculative feedback.

Available tools#

The server publishes four tools. Three are read-only; the fourth submits feedback to a review queue and never edits the documentation.

Security & data#

Endpoint reference: the server is https://mcp.worksby.design/ — streamable HTTP transport; the legacy https://docs-mcp.worksby.design/ address keeps working. You only ever type the address where a client asks for a URL (the Claude app connector, or manual registration) — the plugin path never needs it.

• Approved email addresses only. Access is granted per person and can be revoked immediately.
• Read-only. The server can read documentation (and accept feedback) — nothing else. It has no access to any CRM, system, or customer data.
• Per-install OAuth, no shared keys. Each client holds its own short-lived credential that renews itself and rotates on every renewal — there is no long-lived key to leak, and reusing a rotated credential (the signature of a shared copy) revokes it automatically.
• Audited. Every request is logged with the requester and a timestamp.
• No footprint. Nothing is installed beyond the one-line client setup above.