Model Context Protocol Endpoints

HelpGuides exposes a set of Model Context Protocol (MCP) tools that let AI assistants and agents search, read, write and manage the documentation in your project. This article lists every tool and its parameters.

Endpoint

AI Settings Model Context Protocol tab with the MCP URL — Finding your MCP URL

Each project has its own MCP endpoint on its site's domain:

https://YOUR-DOMAIN/mcp

Copy it from AI Settings on the Model Context Protocol tab. The endpoint uses the Streamable HTTP transport. When Enable Model Context Protocol is off, it returns 404. See AI Settings.

Authentication

The endpoint uses OAuth 2.1. MCP clients such as Claude and ChatGPT handle this for you:

A request without a valid token gets 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource.
The client registers itself using dynamic client registration and sends you to HelpGuides to sign in.
HelpGuides asks you to Approve or Deny the client's access to search and read your articles, create and update draft articles, and publish articles.
The client receives an access token, valid for one hour, and a refresh token it uses to get new ones.

Endpoint	URL
Protected resource metadata	`https://YOUR-DOMAIN/.well-known/oauth-protected-resource`
Authorization server metadata	`https://helpguides.io/.well-known/oauth-authorization-server`
Client registration	`https://helpguides.io/oauth/register`
Authorization	`https://helpguides.io/oauth/authorize`
Token	`https://helpguides.io/oauth/token`

Authorization uses PKCE with S256. Send the access token as Authorization: Bearer ACCESS_TOKEN. A token only works for projects in the HelpGuides account that approved it; using it on another account's project returns 403. The MCP endpoint accepts only these OAuth access tokens, not API keys.

Working copies

Edits made through MCP don't change the live article. update_article, update_article_blocks and add_image_to_article save a working copy by default (saveAsWorkingCopy is true), and each edit builds on the working copy left by the one before.

get_article returns the working copy when there is one, with has_working_copy: true. Always use the block IDs it returns.
publish_article makes the working copy live.
Setting saveAsWorkingCopy to false saves straight to the article, including a published one.

Tools

Tool	What it does	Changes content
`get_whoami`	Names the connected project and site, and summarizes what the tools can do. Call it first.	No
`get_instructions`	Returns usage rules and workflow guidance, plus your project's Prompt Instructions.	No
`get_block_schema`	Returns the JSON structure of every block type.	No
`search`	Searches articles.	No
`get_article`	Returns an article's blocks, or its working copy.	No
`create_article`	Creates a draft article.	Yes
`update_article`	Replaces an article's title and/or all its blocks.	Yes
`update_article_blocks`	Updates, inserts or deletes individual blocks.	Yes
`publish_article`	Publishes or schedules an article.	Yes
`get_categories`	Lists categories.	No
`set_category`	Assigns an article to a category.	Yes
`create_category`	Creates a category.	Yes
`update_category`	Renames, describes or moves a category.	Yes
`build_links`	Adds links to an article from related published articles.	Yes
`get_stale_articles`	Lists articles past their stale date.	No
`get_articles_with_open_comments`	Lists articles with open review comments.	No
`list_agent_comments`	Lists every open review comment.	No
`get_comments`	Returns an article's review comments.	No
`resolve_comment`	Marks a review comment resolved.	Yes
`dismiss_comment`	Dismisses a review comment.	Yes
`create_image_upload`	Starts an image upload.	No
`finish_image_upload`	Checks and publishes an uploaded image.	Yes
`add_image_to_article`	Inserts an image block into an article.	Yes

Every tool that takes postuid_or_url accepts either the article's postuid or its full URL. Tools return JSON; a failure returns {"error": "..."}.

Project and guidance

get_whoami, get_instructions and get_block_schema take no parameters. get_instructions ends with anything you've entered under Prompt Instructions in AI Settings. get_block_schema describes each block type (paragraph, header, list, checklist, table, image, code, quote, callout, faq, raw, video, file, subcategories, hr and api).

search

Parameter	Type	Required	Description
`s`	string	Yes	What to search for. Start with `keyword:` to match exact words instead of meaning.
`limit`	integer	No	Number of results. Default 10, maximum 25.

Results include drafts as well as published articles. Each result has the postuid, title, slug, status, the matching section and an excerpt, so the same article can appear more than once.

get_article

Parameter	Type	Required	Description
`postuid_or_url`	string	Yes	The article's postuid or full URL.

Returns postuid, title, blocks (with their IDs), status and has_working_copy.

Create and edit

create_article

Parameter	Type	Required	Description
`title`	string	Yes	The article's title. The slug is made from it.
`blocks`	array	One of `blocks` or `html`	The body as Editor.js blocks. Preferred.
`html`	string	One of `blocks` or `html`	The body as HTML, converted to blocks. Used only when `blocks` is missing.

Always creates a draft. Returns the new postuid and an edit_url for the editor.

update_article

Parameter	Type	Required	Description
`postuid_or_url`	string	Yes	The article's postuid or full URL.
`title`	string	Yes (may be empty)	The new title. Leave empty to keep the current one.
`blocks`	array	No	A complete set of blocks that replaces all existing blocks. Omit to change only the title.
`saveAsWorkingCopy`	boolean	No	Default `true`. See Working copies.

update_article_blocks

Parameter	Type	Required	Description
`postuid_or_url`	string	Yes	The article's postuid or full URL.
`operations`	array	Yes	Edits applied in order. Each has `action`, `block` and `targetBlockId`.
`saveAsWorkingCopy`	boolean	No	Default `true`.

Action	What it does
`update`	Replaces the block with ID `targetBlockId` with `block`.
`insert`	Inserts `block` before `targetBlockId`, or at the end when `targetBlockId` is null. To insert several blocks in order, target the same block with each insert.
`delete`	Removes the block with ID `targetBlockId`.

{ "postuid_or_url": "https://docs.example.com/article/getting-started", "operations": [ { "action": "update", "targetBlockId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "block": { "type": "paragraph", "data": { "text": "Updated text." } } }, { "action": "insert", "targetBlockId": null, "block": { "type": "header", "data": { "text": "Next steps", "level": 2 } } } ] }

New block IDs must be UUIDs in the standard 8-4-4-4-12 format, or left out so one is generated.

publish_article

Parameter	Type	Required	Description
`postuid_or_url`	string	Yes	The article's postuid or full URL.
`publish_date`	string	No	An ISO 8601 date and time with a UTC offset, such as `2026-03-17T15:00:00-05:00`. A future time schedules the article instead of publishing it now.

Promotes any working copy. Returns the status, the public url and promotedWorkingCopy.

Tool	Parameters
`get_categories`	None. Returns each category's `categoryuid`, name and description.
`set_category`	`postuid_or_url` and `categoryuid` (both required).
`create_category`	`name` (required), `description` and `parentuid` for a subcategory. Returns the new `categoryuid`.
`update_category`	`categoryuid` (required), and any of `name`, `description` and `parentuid`. Empty values keep what's there.

Links and stale articles

Tool	Parameters	Notes
`build_links`	`postuid_or_url` (required)	The article must be published. Finds related published articles and adds a link to this article in up to 5 of them, then lists what changed. See AI Writing Tools.
`get_stale_articles`	`limit` (default 50)	Articles whose Date Stale is today or earlier, with their status, status notes and URL.

Review comments

These tools let an agent act on instructions left in the editor's Review tab. See Review Comments and AI Agents.

Tool	Parameters	Notes
`get_articles_with_open_comments`	`limit` (default 50)	Articles with open comments and how many each has.
`list_agent_comments`	`limit` (default 100)	Every open comment with its article, oldest first.
`get_comments`	`postuid_or_url` (required)	All comments on one article, open, resolved and dismissed, newest first.
`resolve_comment`	`commentuid` (required), `resolution_notes`	Marks the comment resolved by Cowork. Can post to Slack when Notify on Cowork updates is on.
`dismiss_comment`	`commentuid` (required), `resolution_notes`	Closes the comment without edits. Never posts to Slack.

Images

Adding an image takes three tools, so the image itself never passes through the conversation:

create_image_upload (no parameters) returns an uploadId and a write-only uploadUrl that's valid for 10 minutes.
The client uploads the file with an HTTP PUT that includes the header x-ms-blob-type: BlockBlob.
finish_image_upload with upload_id checks the file is a PNG, JPEG, GIF or WebP under 5 MB, publishes it and returns its public url, width and height. Each upload can be finished once.

curl -sS -X PUT -H "x-ms-blob-type: BlockBlob" --data-binary @screenshot.png "UPLOAD_URL"

Then add_image_to_article inserts it:

Parameter	Type	Required	Description
`postuid_or_url`	string	Yes	The article's postuid or full URL.
`image_url`	string	Yes	The https URL from `finish_image_upload`.
`alt_text`	string	Yes	What the image shows.
`caption`	string	No	Text shown under the image.
`insert_before_block_id`	string	No	The block to insert before. Omit to add the image at the end.
`width`, `height`	integer	No	Pixel size from `finish_image_upload`.
`saveAsWorkingCopy`	boolean	No	Default `true`.

Recommended workflow

Call get_whoami and get_instructions.
Call search to find existing articles before writing a new one.
Call get_block_schema, then create_article, or get_article followed by update_article_blocks.
Call get_categories and set_category.
Review the draft or working copy in HelpGuides, then publish it in the editor or with publish_article.

To connect an assistant, see Add Claude as an MCP Connector and Add ChatGPT as an MCP Connector.