Docs MCP — setup & access — worksby.design Docs

Connect your AI assistant — the Claude app, Claude Code or Codex — to the Works by Design HubSpot documentation, so it builds the way HubSpot is actually built. Setup takes about a minute. Access is limited to approved email addresses. For the overview, see the Docs MCP page.

Overview#

The Docs MCP server connects your AI assistant to the Works by Design HubSpot technical documentation — hundreds of hours of real build and troubleshooting experience, written up as it was solved. Once connected, your assistant searches and reads it live while helping you: ask for a UI extension, a CMS module, a quote template or a complete HubSpot app and it builds from patterns proven to work, or point it at existing code and it troubleshoots against current best practice — instead of guessing from general training knowledge.

It works whether you develop on HubSpot daily or you're describing your first build in plain English: you ask, your assistant does the reading. The connection uses the Model Context Protocol (MCP) and works with the Claude app (web and desktop), Claude Code and Codex.

Endpoint: https://mcp.worksby.design/ — streamable HTTP transport (the legacy https://docs-mcp.worksby.design/ address keeps working). The connection is read-only.

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. Access is limited to approved email addresses; if yours isn't approved yet, get in touch.

What you can read: every sign-in grants the HubSpot technical documentation. Additional documentation sets (business & sales-engineering context under business/, server infrastructure under webserver/) are granted per person — docs_list shows exactly what yours includes.

Tip

For AI agents: for any HubSpot question, call docs_get with README.md first — it's a routing index with a one-line "Load when…" note per file — then docs_get the files it points to. Use docs_search only as a fallback when the index doesn't clearly identify the right file.

Connect — Claude web & desktop app#

The simplest route: no terminal, nothing to install. Same on Windows and macOS, and in the browser.

In Claude, open Settings → Connectors.
Look for worksbydesign in the list. If it's there, click Connect and skip to the sign-in below.
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/
```
Leave OAuth Client ID and Client Secret empty — the connector registers itself. Click Connect to start the browser sign-in.

Note

No "Add custom connector" button, and no worksbydesign connector listed? That isn't you missing it. On a managed or company Claude plan an administrator can disable custom connectors, and the option simply isn't shown. Ask whoever manages your Claude workspace to allow custom connectors — or use Claude Code below, which is unaffected.

Connect — Claude Code#

The standard path is the plugin: two commands typed into Claude Code itself (the chat input — VS Code panel, desktop app, or the terminal app), no system terminal needed. It installs the documentation server and the general-purpose skills in one go:

/plugin marketplace add https://worksby.design/git/plugins.git
/plugin install toolkit@worksby-design

When Claude Code asks you to authenticate worksbydesign (it prompts on first use — or run /mcp and choose Authenticate), that opens the browser sign-in described below. One setup covers VS Code, the desktop app's Claude Code and the terminal — they share one configuration.

Then turn on auto-update: /plugin → Marketplaces → worksby-design → Enable auto-update. Claude Code leaves this off for marketplaces outside Anthropic's own; without it, new skills we publish never reach you.

toolkit carries the universal skills — starting with quote-builder (customer quote PDF → live HubSpot quote), which works with the standard technical access. Doing presales demos? If your access includes the business-context documentation, also run /plugin install toolkit-demos@worksby-design for the four demo skills (demo pages, workspaces, customer context, brand capture) — without that grant they refuse politely, so only install what your access covers.

Alternative — documentation only, no plugin#

Run this in a normal terminal — PowerShell or Windows Terminal on Windows, Terminal on macOS. Not inside a Claude Code session:

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

Keep --scope user. Without it Claude Code defaults to local scope and registers the server only for the folder you ran the command in — it then silently disappears when you open any other project. This is the single most common setup mistake.

Adding is not signing in. The command only registers the address. To finish, open Claude Code, run /mcp, and choose Authenticate next to worksbydesign. It takes effect immediately — confirm with claude mcp get worksbydesign (✓ Connected).

claude not found? On macOS, open Claude Code and run /install-cli, then close and reopen your terminal. On Windows, the CLI is installed with Claude Code itself — reopen the terminal so it picks up PATH. Check with claude --version.

Had the manual entry before installing the plugin? No conflict — both point at the same address and Claude Code connects once; your existing sign-in keeps working.

Connect — Codex#

Add the server, then sign in:

codex mcp add worksbydesign --url https://mcp.worksby.design/
codex mcp login worksbydesign

codex mcp login opens the same browser sign-in described below.

Codex reads the same documentation as Claude Code. The optional demo-builder toolkit — branded demo pages, run sheets and workspaces — is a Claude Code plugin with no Codex equivalent; on Codex you point the assistant at the demo-methodology specs directly (business/skills/specs/), when your grant includes them.

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:

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.
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.
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. It asks your assistant to store the guidance durably — Claude Code in ~/.claude/CLAUDE.md, Codex in ~/.codex/AGENTS.md — so it governs every future session instead of just the current chat.

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. For Codex, add or update it in ~/.codex/AGENTS.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.

Tool	Type	What it does
`docs_list`	read	List every documentation file your grant can read (path + title + hub). The starting point; the technical index is `README.md`, other granted hubs index at `<hub>/README.md`.
`docs_search`	read	Keyword search across the documentation. Returns ranked results with snippets.
`docs_get`	read	Return the full Markdown of one file by path.
`docs_feedback`	queue	Report a verified error or gap in the docs. Submissions are queued for human review and never modify the documentation directly.

Security & data#

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.

Note

Access is personal and per install. If a teammate leaves or an install should no longer have access, let us know and we'll revoke it — it stops working immediately.