Create an article using Claude

HelpGuides ships an MCP (Model Context Protocol) server that lets Claude draft articles in your knowledge base directly from a chat conversation. Point Claude at a file, a feature, or a paste of release notes, and it will create the article for you — title, slug, category, markdown, and SEO metadata included.

Every article Claude creates is saved as a draft. You always review and publish from the HelpGuides editor — Claude cannot publish on your behalf.

Before you start

You'll need:

• A HelpGuides account on the PRO plan (the MCP server is PRO-only).
• An API key — mint one at Settings → API Keys in the HelpGuides editor. The full token is shown once, so copy it somewhere safe.
• Claude Code (CLI, desktop app, or IDE extension) or Claude Desktop.

Note on Claude.ai (web app): the Claude.ai "Custom Connectors" feature requires OAuth, which the HelpGuides MCP does not yet implement. To use Claude on the web, see Option 3 below for a manual workflow that still works well.

Option 1: Claude Code (recommended)

Claude Code is the best fit if you're already authoring articles alongside code — it can read files in your repo and turn them into documentation. It's available as a CLI, a desktop app (Mac/Windows), and as IDE extensions for VS Code and JetBrains. All three share the same MCP configuration, so once you've added the HelpGuides MCP it works everywhere you use Claude Code.

1a. Set up via the CLI (fastest)

From any terminal, run:

claude mcp add --transport http helpguides https://helpguides.app/api/mcp \
  --header "Authorization: Bearer hg_live_YOUR_TOKEN"

Replace hg_live_YOUR_TOKEN with the key you minted. There's also a "Copy Claude Code command" button on the API Keys page that gives you this command with the token already embedded.

By default this saves to your user scope (~/.claude.json), so the MCP is available in every Claude Code session — terminal, desktop, and IDE. To scope it to a single project instead, add -s project (writes to .mcp.json in the current repo).

1b. Set up via the Claude Code desktop app

If you prefer a GUI:

1. Open the Claude Code desktop app.
2. Click the Settings (gear) icon → MCP Servers → Add server.
3. Fill in:
   • Name: helpguides
   • Transport: HTTP
   • URL: https://helpguides.app/api/mcp
   • Headers: add a header with key Authorization and value Bearer hg_live_YOUR_TOKEN
4. Click Save. The server should show a green "connected" indicator within a few seconds.

The desktop app writes to the same ~/.claude.json file as the CLI, so changes made in either place are picked up by the other.

1c. Set up via the VS Code or JetBrains extension

In the Claude Code IDE extension:

1. Open the Claude Code panel (sidebar icon).
2. Click the ⋯ menu → Settings → MCP Servers.
3. Choose Add HTTP server and enter the same name, URL, and Authorization header as above.
4. Save and reload the panel.

If you'd rather edit JSON directly, both extensions read the same ~/.claude.json user-scope file the CLI uses — so any of the three setup paths will surface the MCP in all clients.

1d. Edit the config file directly (advanced)

If you'd rather skip the wizard, open ~/.claude.json (created by Claude Code on first run) and add an entry under mcpServers:

{
  "mcpServers": {
    "helpguides": {
      "type": "http",
      "url": "https://helpguides.app/api/mcp",
      "headers": { "Authorization": "Bearer hg_live_YOUR_TOKEN" }
    }
  }
}

For a project-scoped install, put the same block in a .mcp.json at the repo root and commit it (without the token — use an environment variable reference instead if you check it in).

2. Verify the connection

Start a Claude Code session (any client) and ask:

Use helpguides to run whoami.

You should see your company name, plan, and the key it's authenticated as.

3. Draft your first article

Try a prompt like:

Use helpguides to draft an article titled "Resetting your password" under the Getting Started collection. Cover: requesting a reset email, the link expiry, and what to do if the email doesn't arrive.

Claude will call list_collections to find the right category ID, then call create_article with a complete markdown draft. Open /editor/articles in HelpGuides, filter by Draft, review, and click Publish.

Option 2: Claude Desktop

Claude Desktop (the standalone Claude.ai client, not Claude Code) works the same way — the only difference is the location of the config file.

1. Edit the Claude Desktop config

Open the config file for your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it. Then add:

{
  "mcpServers": {
    "helpguides": {
      "type": "http",
      "url": "https://helpguides.app/api/mcp",
      "headers": { "Authorization": "Bearer hg_live_YOUR_TOKEN" }
    }
  }
}

Or use the in-app UI: Settings → Developer → Edit Config, which opens the same file.

2. Restart Claude Desktop

After saving, fully quit and relaunch Claude Desktop (Cmd+Q / right-click tray → Quit — closing the window isn't enough). The helpguides tools should appear in the tool picker (slider/plug icon in the composer).

3. Draft an article

Ask Claude exactly as you would in Claude Code — for example:

Use helpguides to draft an article on troubleshooting failed payments, filed under Billing.

Option 3: Claude web app (manual workflow)

If you're using claude.ai in your browser, the MCP server is not directly connectable yet. You can still get the same result with a simple two-step flow:

1. Draft in Claude. Ask Claude to write the article as markdown — title, description, and body. Example prompt:

   Write a HelpGuides knowledge-base article titled "Inviting teammates". Output a JSON object with title, description, and a content field containing markdown. Audience is non-technical end users; keep it under 400 words.

2. Create the article in HelpGuides. Open the HelpGuides editor → Articles → New article, paste the title and description, then paste the markdown into the body. Save as draft, review, and publish.

This takes about 30 seconds longer than the MCP flow but works from any browser, with no setup.

Prompt examples

Copy-and-paste prompts to get you started. They all assume you've already added the helpguides MCP server (Option 1 or 2).

Draft from scratch

Use helpguides to draft a new article titled "How billing works", filed under the Billing collection. Explain monthly vs. yearly plans, what's included in the free tier, how to upgrade, and where to find invoices. Target audience: non-technical admins. Keep it under 500 words and finish with a short FAQ.

Draft from a source file

Read src/lib/webhooks.ts and use helpguides to draft an article titled "Webhook events reference" under the Developers collection. List every event type, the payload shape, and one example use case per event. Include a code block for the JSON payload.

Turn changelog notes into a product update

Here are this week's changelog entries:

• Added dark-mode preview for the chatbot
• Fixed a bug where draft articles appeared in search
• New "Resend invite" button on the Users page

Use helpguides to draft a customer-facing product update titled "What's new — May 2026" in the Product Updates collection. Friendly tone, one short paragraph per item.

Rewrite an existing article

Use helpguides get_article to fetch the article with slug embedding-the-helpguides-chatbot, then rewrite the intro to be shorter and add a new section on installing via Google Tag Manager. Save it back with update_article.

Bulk-create from an outline

I'm going to paste an outline with 5 article titles and one-line descriptions. For each one, use helpguides to create a draft article under the Getting Started collection. Write 200–300 words per article and link related ones at the bottom of each.

Audit and improve SEO

Use helpguides to list all articles in the Account collection, then for each one suggest a better metaTitle and metaDescription (under 60 and 155 characters). When I approve, update them with update_article.

Adding images to articles

Claude can upload images to your HelpGuides media library and embed them inline in the markdown body — useful for screenshots, diagrams, or UI tours.

How it works

The MCP exposes an upload_image tool. When Claude calls it, the image is stored on your HelpGuides account and the tool returns a public URL you can drop straight into markdown as ![alt text](url).

There are two ways to get an image to Claude in the first place:

• From a local file (Claude Code / Desktop) — drag the image into the chat, or reference a path: "Read ./screenshots/dashboard.png and upload it via helpguides."
• From a URL — paste any public image URL and ask Claude to fetch and upload it.

Example prompts

Add a single screenshot to a new article:

Use helpguides to draft an article titled "The dashboard at a glance" under Getting Started. I'm attaching one screenshot — upload it via upload_image and embed it near the top with descriptive alt text. Then explain each section of the dashboard underneath.

Add multiple screenshots to walk through a flow:

I'm attaching 4 screenshots of the onboarding flow in order: signup, email verify, create-company, invite-team. Use helpguides to create an article titled "Setting up your workspace" under Getting Started. Upload all 4 images with upload_image, embed each one above the matching step, and write 2–3 sentences per step.

Add an image to an existing article:

Fetch the article with slug inviting-teammates using get_article. I'm attaching a screenshot of the Users page — upload it via upload_image, then insert it right after the "Sending an invite" heading. Use update_article to save.

Generate alt text for accessibility:

Look at the screenshot I'm attaching, describe what's in it concisely (under 120 chars), upload it via helpguides upload_image, and then embed it in the article chatbot-color-customization after the first paragraph with that description as alt text.

Limits and tips

• 2 MB max per image. Compress large screenshots first (TinyPNG, Squoosh, or pngquant).
• 10 uploads/minute per API key. For bulk image work, pace your prompts or let Claude back off automatically.
• Always use descriptive alt text. It improves accessibility, SEO, and how the chatbot answers visual questions.
• Crop and annotate before uploading. Claude won't redact sensitive data on screenshots — review them first.

What Claude can and cannot do

Capability	Claude Code / Desktop (via MCP)	Claude web (manual)
List your collections / categories	✓	—
Create a draft article	✓	You paste it in
Update an existing article	✓	You paste edits in
Upload images and embed them	✓ (up to 2 MB)	Upload manually in the editor
Publish an article	✗ — drafts only, by design	✗ — you always publish manually
Delete an article	✗	✗

The draft-only restriction is intentional: it lets you use AI for the heavy lifting while keeping a human in the loop for what your customers actually see.

Limits

If you're authoring in bulk:

• 60 requests/minute and 1,000/hour per API key.
• 10 image uploads/minute per key.
• 2 MB max per image.

If you hit a limit, Claude will surface a clear error and back off — you can usually just wait a minute and retry.

Troubleshooting

"No HelpGuides API key found in this MCP session" — your Claude client isn't sending the Authorization header. Re-add the MCP with the --header flag (Claude Code CLI), check the headers in the Settings UI (desktop app / IDE extension), or verify the headers block in your config file, then restart the client.

Server shows as "disconnected" in Claude Code desktop — check that the URL is https://helpguides.app/api/mcp (no trailing slash) and that the token starts with hg_live_. Click Reconnect in the MCP Servers panel.

"REST API access requires the PRO plan" — your company is on the free plan. Upgrade from the sidebar Upgrade button in the HelpGuides editor.

"Unknown categoryId" — Claude guessed a category that doesn't exist. Tell it: "Call list_collections first, then use one of the IDs it returns."

Image upload failed — check the file is under 2 MB and is a standard format (PNG, JPG, GIF, WebP). If you're uploading several at once, you may be hitting the 10/minute limit — wait 60 seconds and retry.

Articles don't appear on the public portal — they're drafts. Go to /editor/articles, filter by Draft, and click Publish.

See also

• Embedding the HelpGuides chatbot on your site
• HelpGuides editor → Settings → API Keys to mint or revoke tokens