← Back to Docs Docs

Docs MCP —
setup & access.

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.

On this 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.

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.

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

Two steps: add the server in a terminal, then authenticate inside Claude Code. There is no key to paste.

Step 1 — add the server

Run this in a normal terminal — PowerShell or Windows Terminal on Windows, Terminal on macOS, or the terminal built into VS Code. Not inside a Claude Code session: Claude Code cannot add a server to itself, because its tool shell often can't see the claude command and a running session has already loaded its server list.

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.

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 — if the command isn't recognised, reopen the terminal (a fresh one picks up PATH), or reinstall Claude Code. Check with claude --version.

Step 2 — authenticate

Adding is not signing in. The command above only registers the address, and it reports success while the server is still unauthenticated. To finish, open Claude Code, run /mcp, and choose Authenticate next to worksbydesign (it also prompts on first use). That opens the browser sign-in described below.

/mcp is a command inside Claude Code — the VS Code extension's chat panel, the Claude desktop app's Claude Code section, or claude running in a terminal all work. Typing /mcp into a plain system terminal returns "command not found"; that means you're in the wrong place, not that anything is broken.

Authentication takes effect immediately — no restart needed. Confirm any time with claude mcp get worksbydesign, which should report ✓ Connected.

This one setup covers VS Code with the Claude Code extension, the Claude desktop app's Claude Code section, and the terminal — they share one configuration, so there is nothing extra to do for each.

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:

  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 nothing to copy.

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

After connecting, paste this 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.

ToolTypeWhat it does
docs_listreadList 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_searchreadKeyword search across the documentation. Returns ranked results with snippets.
docs_getreadReturn the full Markdown of one file by path.
docs_feedbackqueueReport 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.
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.