/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Hosted connector tools

Hosted connector tools

Every tool of the hosted MCP connector at api.syntext.dev/mcp: arguments, results, scopes and annotations

37 min read

The hosted MCP connector at https://api.syntext.dev/mcp lists the 47 tools below, in this order. Read tools need the docs:read scope; write tools need docs:write and are left out of tools/list for a read-only connection.

Every project-scoped tool takes project: a project ID, slug or subdomain from list_projects. A project outside your workspaces is "not found".

Annotations

Every tool declares a title and all four MCP annotation hints, so a client knows what a call does before it makes it.

ToolsreadOnlyHintdestructiveHintidempotentHintopenWorldHint
Read toolstruefalsetrue (ask_docs: false)false
edit_page, create_page, update_page, move_page, delete_page, update_navigation, add_changelog_entry, publish_changes, discard_changes, trigger_buildfalsetruefalsefalse
upload_image, draft_page_from_gap, suggest_edit, request_review, preview_buildfalsefalsefalsefalse
fix_deprecated_syntaxfalsefalsetruefalse
•
Destructive tools can overwrite or remove content, or publish a new version of your live site. Clients that honour annotations, such as Claude and ChatGPT, ask you before each call. In draft or pull_request mode they change nothing live, but the annotation can't depend on an argument, so they are still marked destructive.
•
upload_image only adds a new file and never replaces one; draft_page_from_gap and suggest_edit only save unpublished changes; request_review only asks people to look; preview_build only builds a preview at its own URL. None of them changes the live site.
•
fix_deprecated_syntax only saves an unpublished draft or pull request, and running it again on the result finds nothing more to change, so it's idempotent.
•
openWorldHint is false for every tool: each one only reaches your own Syntext workspaces and the repositories connected to them. No tool sends a request to your API or any other outside service.

Each tool also declares the OAuth scope it needs in securitySchemes. Arguments are validated before anything runs: a bad argument returns an error naming the field and what to send.

Results and errors

•
Every tool returns its result as structuredContent, with the same JSON in a text block, and declares an outputSchema describing it, so a client can read fields rather than parse text.
•
A tool that can't do what was asked returns isError: true with a message that says why and what to do next: "Project "x" not found or you don't have access. Use list_projects…", "Nothing was saved: …". Nothing is half saved.
•
Empty results — when something doesn't exist yet or is empty (no builds, analytics, docs gaps, stale pages, changelog, unpublished changes, page history or API reference yet, no differences in a diff, a search with no matches, no code drift), the tool returns a normal result with a note saying why it's empty and what would fill it, not an error. publish_changes and discard_changes with nothing to publish or discard return unchanged: true and change nothing.
•
Real problems are still errors: a page, file or endpoint you named that isn't there (with close matches when there are any), a bad argument, no access, a plan limit, or a setup problem such as a missing repository.
•
Lists are paged with limit and offset and return { items, total, offset, nextOffset }; nextOffset is null on the last page.
•
Text over 120,000 characters is cut, with a note at the end.

Read and cite

Search documentation. Searches the published docs of every project you can access (up to 20), or of one project, and returns up to 10 pages.

ArgumentTypeRequiredDescription
querystringYesNatural language or keywords, up to 500 characters
projectstringNoLimit the search to one project

Returns { "results": [{ "id", "title", "url" }] }. With more than one project, titles start with the project name.

fetch

Fetch documentation page. The full published text of a page, by the id that search returned.

ArgumentTypeRequiredDescription
idstringYesA result id from search, unchanged

Returns { "id", "title", "text", "url", "metadata": { "project", "path", "truncated"? } }.

search and fetch

search and fetch follow the contract ChatGPT's deep research and company knowledge use. Both send their result as structuredContent and as JSON text, and declare an outputSchema. An id has the form <project id>:<page path>.

•
Published content only. Both read what your last build published — the same content the docs assistant answers from.
•
Gated content is excluded. Sections behind audience gating never appear in results, and fetch leaves them out; a page that is entirely gated is not found.
•
fetch caps a page at 100,000 characters and marks a cut page with metadata.truncated: "true".

list_projects

List projects. { "projects": [...] }: your projects, with id, name, slug, doc site url, repoConnected and contentSource — where the pages live: hosted (written in Syntext), github (a connected repository) or upload (published with stx deploy). No arguments.

search_docs

Search one project's docs. The best-matching sections in one project, with page path, section heading, a 500-character excerpt and relevance.

ArgumentTypeRequiredDescription
projectstringYes
querystringYes
limitintegerNo1–25, default 10

get_page

Get published page. The published text of one page as Markdown, with its title and URL.

ArgumentTypeRequiredDescription
projectstringYes
slugstringYesPage path, e.g. guides/quickstart

ask_docs

Ask the docs assistant. Asks the project's docs assistant and returns its answer, written from the project's published docs, with the pages it used.

ArgumentTypeRequiredDescription
projectstringYes
questionstringYesUp to 2,000 characters

Returns { "answer", "citations": [{ "path", "url" }], "project" }. Each call counts as one AI query toward the plan; when they are used up, the tool says so and asks nothing. The old name ask_question still works but is not listed.

list_pages

List source pages. The project's MDX pages, paged (limit 1–100, default 100; offset): the files in its connected repository, or the pages of a project written in Syntext. Returns { items, total, offset, nextOffset }; each item has the file path and a title.

Reading an unpublished change

list_pages, get_page_source, get_page_history, get_navigation and get_site_config take an optional changeId from list_changes or a write's result. With it they read that unpublished change instead of the live content: the branch of a pull request the connector opened ("pr-<number>"), or the saved draft of a project written in Syntext ("draft"). Use it to check a page, the sidebar or syntext.json as they will be once the change is published.

When you name a page that isn't on the live site but is in one of the connector's open pull requests, the error says which: guides/new.mdx isn't on the live site, but it's in an unpublished change: pr-42 ("Add webhooks guide"). Pass changeId: "pr-42" to read or change it there.

get_page_source

Get page source. The raw source of one file, from the connected repository or the pages written in Syntext: { "path", "sha", "content" }. Pass sha to edit_page or update_page as expectedSha.

ArgumentTypeRequiredDescription
projectstringYes
pathstringYesRelative to the docs root, e.g. guides/quickstart.mdx
changeIdstringNoRead this unpublished change ("draft" or "pr-<number>", from list_changes) instead of the live content

get_page_history

Get page history. The recent changes to one file, newest first: { "path", "source", "entries", "nextCursor" }. Each entry has author, date and message, plus:

•
for a project written in Syntext, the revision number and whether it is published — the same history as the editor's History;
•
for a GitHub project, the commit sha and its url.
ArgumentTypeRequiredDescription
project, pathstringYes
limitintegerNo1–50, default 20
cursorstringNonextCursor from the previous call, for older entries; null when there are none
changeIdstringNoRead this unpublished change ("draft" or "pr-<number>", from list_changes) instead of the live content

get_navigation

Get navigation. The sidebar as the build reads it: navigation (groups with their pages, nested groups kept), tabs, and configFile (the file that defines them, or null). With no navigation configured, a note says the sidebar comes from the folder structure. Arguments: project, and changeId to read an unpublished change.

get_site_config

Get site configuration. The project's syntext.json (or syntext.yml) from the repository root or docs folder, parsed: { "configFile", "source", "theme", "config" }. source is "repository", or "hosted" for the config file of a project written in Syntext. A project published with stx deploy, or a hosted project with no config file yet, returns its saved settings, with source: "project settings". Arguments: project, and changeId to read an unpublished change.

get_changelog

Get changelog. Two lists, each paged:

•
page: the <Update> entries on the changelog page (title, date, tags), newest first, with the page url. If the page doesn't exist, a note says so.
•
generated: changelog entries Syntext generated from builds (id, title, published, createdAt, body).
ArgumentTypeRequiredDescription
projectstringYes
pathstringNoChangelog page, default changelog.mdx
limit, offsetintegerNoPaging

API reference

These three tools read the endpoint list Syntext saves when a production build publishes your site. It comes from three sources:

sourceWhere the endpoint is documentedspec
openapiYour OpenAPI specsThe spec's title
pageMDX API reference pages: pages with protocol: rest, method and endpoint in their frontmatterAPI reference pages
annotation@stx.http annotations in your codeCode annotations

The same endpoint (same method and path) documented in several places is listed once: from the OpenAPI spec if there is one, otherwise from the page, otherwise from the annotation. It keeps the page link and file location the others had.

A project with no API reference yet gets an empty list with a note saying how to add one. Members of the project's workspace see every endpoint.

Note

Projects published before 15 November 2026 read their API reference pages from the published page text until the next publish, so description and auth are missing for those endpoints until you publish again.

list_endpoints

List API endpoints. The endpoints in the API reference, paged under items: id, method, path, summary, operationId, tags, deprecated, the spec it belongs to, source (openapi, page or annotation), sourceLocation for annotations (the file and line of the @stx.http tag, such as src/routes/users.ts:42) and docUrl, the page that documents it. Also returns specs (each with its title, source, endpointCount and servers — pages and annotations have none — a server marked sandbox: true when the spec flags it with x-syntext-sandbox) and every tags value.

ArgumentTypeRequiredDescription
projectstringYes
tagstringNoOnly endpoints with this tag
specstringNoOnly this spec, by its title, for projects with several
limit, offsetintegerNoPaging, limit 1–100, default 50

search_endpoints

Search API endpoints. Endpoints matching query by path, summary, description, operation ID, tags and parameter names, best first, each with a score and the same fields as list_endpoints, including source and sourceLocation.

ArgumentTypeRequiredDescription
project, querystringYesquery up to 500 characters
limitintegerNo1–50

get_endpoint_docs

Get endpoint documentation. Reads the documentation of one endpoint in the published API reference: description, parameters, requestBody, responses, auth (how it authenticates), servers, exampleRequests, source, sourceLocation and docUrl. What comes back depends on the source:

•
OpenAPI — everything the spec says, with a request body example and exampleRequests in cURL, JavaScript and Python.
•
API reference page — what the page documents: its parameters, body fields and responses, and the page's own code examples as exampleRequests.
•
Annotation — what the @stx.http annotation documents, with no exampleRequests.

When the page or annotation doesn't say how the endpoint authenticates, auth is null and note says so.

ArgumentTypeRequiredDescription
projectstringYes
endpointstringYesThe endpoint's id from list_endpoints or search_endpoints, such as GET /v1/customers/{id} (a concrete path like GET /v1/customers/cus_123 also works), or its operationId
specstringNoOnly this spec, by its title

It reads the docs only and sends no request to your API. The old name get_endpoint still works but is not listed.

Every endpoint in list_endpoints and search_endpoints results now has an id to pass here.

Run the docs

get_analytics

Get docs analytics. How readers used the docs over a period:

•
summary: page views, unique visitors, average time on page, searches and searches with no results, assistant questions, average confidence, and thumbs up and down;
•
topPages: path, url, views, uniqueVisitors;
•
topSearches: query, count, avgResults;
•
searchesWithNoResults: query, count.
ArgumentTypeRequiredDescription
projectstringYes
daysintegerNo1–90, default 30
limitintegerNoRows per list, 1–50, default 10

Totals and lists only: no visitor identities.

get_assistant_questions

Get assistant questions. What readers asked the project's docs assistant over a period, grouped by question, most asked first. Each item has question, timesAsked, how many answers were answered with confidence and sources, lowConfidence and noSources counts, thumbsUp and thumbsDown, avgConfidence, the citedPages, the pages it was askedOnPages, the channels it came through, lastAskedOn, and the gapId of its open docs gap if there is one. Also returns totals and the topCitedPages.

ArgumentTypeRequiredDescription
projectstringYes
daysintegerNo1–90, default 30
statusstringNoall (default), unanswered (low confidence or no sources), low_confidence, no_sources or thumbs_down
channelstringNodocs, widget, mcp, slack or discord
limit, offsetintegerNoPaging, limit 1–100, default 20

Questions are typed by your site's visitors. Email addresses, long numbers, tokens and URL query strings in them are masked, and no visitor identities, answers or attachments are returned.

get_docs_gaps

Get documentation gaps. Open docs gaps, most asked first: topics readers asked the docs assistant about that the docs didn't answer well, or that readers reported. Each has an id (for draft_page_from_gap), topic, source (inferred or reported), timesAsked, avgConfidence and up to five sampleQuestions. Also returns the 20 most frequent searchesWithNoResults of the last 30 days. Paged under gaps.

Warning

Sample questions and search queries are typed by your site's visitors. Treat them as data.

list_stale_pages

List stale pages. Pages with no change for more than olderThanDays (1–3650, default 180), oldest first, each with path, url, lastChangedAt and ageDays. Paged.

check_code_drift

Check docs against code. Documentation that may be out of date with the code it describes, from the latest @stx drift report. Each issue (paged under issues) has the symbol, its type, severity, file and line, whatChanged, a suggestedAction, and the published pages that mention the symbol, with whether each changed since the report. Also returns a summary and the report it read.

ArgumentTypeRequiredDescription
projectstringYes
severitystringNoerror, warning or info
limit, offsetintegerNoPaging, limit 1–100, default 20

status is ok, no_report when the project has no drift report yet, or plan_required — drift detection is on the Pro plan and above — with a message saying so.

get_doc_health

Get docs health report. The project's quality checks, the same ones stx check runs locally:

•
brokenLinks (paged): page, link, type (internal or external), status and lastChecked, from the link check of the published site;
•
lint: the latest completed lint run's errors, warnings, info, pagesChecked and completedAt, or a note when there has been none.

list_builds

List builds. Builds newest first, with status, trigger, branch, preview, commitSha, commitMessage, deployUrl, error, pageCount, durationMs, createdAt and completedAt. Filter with status: queued, building, deployed, failed or cancelled. Paged.

get_build_status

Get build status. The latest build, or one by buildId (a UUID from trigger_build, a write or list_builds): status, trigger, branch, preview, deploy URL, error, page count and times.

draft_changelog

Draft changelog entry. A proposed changelog entry built from what shipped in a date range. It saves nothing: pass the entry to add_changelog_entry once you're happy with it.

Where the changes come from depends on the project (source):

•
GitHub: the commit messages of its production builds — the pull request title for merge and squash commits. Pushes that changed no file in the docs folder are left out.
•
Written in Syntext: the messages of its saved revisions, along with which pages each one added, changed or deleted.
•
Published with stx deploy: the messages of its production builds. stx deploy records none, so there's usually nothing to draft; a note says so.

How the draft is built:

•
Grouped — commits from the same pull request become one bullet, then commits with the same type and scope (fix(auth): …), then rebuilds of the same change. Pull request numbers stay in the bullet as (#123).
•
Noise left out — merge commits, maintenance commits (chore, ci, build, test, style), typo-only fixes and changes to the changelog page itself.
•
Sorted into sections — Added, Changed, Fixed and Removed, by commit type (feat → Added, fix → Fixed), then by the pages a revision added or deleted, then by the leading verb (Add, Fix, Remove). Anything else is Changed.
•
No repeats — a change already in a changelog entry dated in the range (by its pull request number or its description) is skipped, and skipped names the entry.
•
At most 25 bullets — the rest are counted in truncated, and the body and note say so.

It returns:

•
entry: title, date, tags and a Markdown body with the sections — the same fields add_changelog_entry takes. null when there's nothing new to announce;
•
sections: the bullets of each section (added, changed, fixed, removed);
•
truncated: how many changes were left out by the 25-bullet limit;
•
skipped: count, and reasons, each with its reason, count and up to three examples;
•
sources: the builds or revisions it read, oldest first (the newest 50), each with its kind, ref, date, commitSha and first line of message;
•
codeSignals: API changes from the latest @stx drift report in the range, on plans with drift detection;
•
note: when the range is empty, everything was skipped, the draft is short or cut, or the changelog page couldn't be read.
ArgumentTypeRequiredDescription
projectstringYes
from, tostringNoFirst and last day, YYYY-MM-DD (UTC). to defaults to today. Up to 366 days
daysintegerNoDays to cover when from is left out, 1–90, default 30
pathstringNoThe changelog page: changes to it are left out, and its entries are checked for repeats. Default changelog.mdx

list_changes

List unpublished changes. { "source", "changes" }: what is saved but not yet on the live site. Each change has a changeId, its title, the files (with their status) or branch, who made it (author, authors), createdAt and updatedAt, and where to review it (reviewUrl, and previewUrl for a pull request).

•
Written in Syntext: at most one change, "draft" — every saved edit the live site doesn't show yet, whoever made it, including the editor's Save draft.
•
GitHub: one change per open pull request the connector opened against the production branch, "pr-<number>". Pull requests people opened themselves are not listed and can't be published or discarded here.

Argument: project.

diff_changes

Show changes as a diff. A unified diff of an unpublished change against the live documentation, file by file: each file has path, status, additions, deletions and diff (binary: true for images). Diffs are capped at 100,000 characters in all; past that, files are listed without their diff and truncated is true.

ArgumentTypeRequiredDescription
project, changeIdstringYes"draft" or "pr-<number>", from list_changes
pathstringNoOnly this file

Write, review and publish

Every tool here needs docs:write and (once it applies) a verified email. They work on both kinds of project you can edit, and most take a mode:

Projectmode: "commit" (default)mode: "draft"mode: "pull_request"
GitHub (connected repository)One commit to the production branch, then a build that publishesA pull request, as pull_requestA new syntext/mcp-… branch, one commit, a pull request; nothing published
Written in Syntext (pages kept in Syntext, edited in the web editor)One new revision, then a publishOne new unpublished revision, like the editor's Save draftRefused: there are no branches or pull requests

Drafts and pull requests are changes you can list, diff, add to, send for review, publish or discard — see Draft, review and publish.

Adding to a change

Every write tool here — edit_page, create_page, update_page, move_page, delete_page, update_navigation, add_changelog_entry, upload_image, draft_page_from_gap, fix_deprecated_syntax and suggest_edit — takes an optional changeId, from list_changes or an earlier write's result. With it, the write reads from and adds to that unpublished change instead of the live docs:

•
GitHub ("pr-<number>"): one more commit on the pull request's branch.
•
Written in Syntext ("draft"): one more unpublished revision in the project's draft.

So you can build one change across several tools — create a page, upload its image, add it to the sidebar — and review and publish it once.

•
Nothing is published. With changeId the default mode is "draft"; changeId with mode: "commit" is refused and nothing is saved.
•
Only the connector's pull requests. A pull request people opened themselves is refused: add to it on GitHub instead.
•
The result names the change. Every write returns the changeId that holds it, ready to pass to the next write.
json
{
"project": "acme",
"path": "guides/webhooks.mdx",
"title": "Webhooks",
"navGroup": "Guides",
"changeId": "pr-42"
}

A project published with stx deploy keeps its files on your machine, not in Syntext, so every write tool and trigger_build refuse it: "This project is published with stx deploy from the CLI, so its source files are not stored in Syntext. Edit them locally and run stx deploy, or import them in the Syntext dashboard." Its pages can still be read and searched.

Results

Every write returns structured content (and the same JSON as text):

ResultFields
Commit (GitHub)mode: "commit", committed: true, commitSha, commitUrl, buildId, published, and buildError if the build couldn't start (the commit is kept)
Revision (written in Syntext)mode: "commit", committed, revision (the new revision number), buildId, published, and buildError if the publish couldn't start (the revision is kept). A change identical to the current file saves nothing: committed: false, unchanged: true, revision: null
Draft (written in Syntext)mode: "draft", committed, revision, changeId: "draft", published: false
Pull request (GitHub)mode: "pull_request", pullRequestUrl, pullRequestNumber, branch, commitSha, previewUrl, changeId: "pr-<number>", published: false. Adding to an existing pull request with changeId returns the same fields for that pull request

Each tool adds its own fields, such as path, created, navigationUpdated, redirect, or editsApplied, additions and deletions. trigger_build and preview_build return { buildId, status, preview }, plus branch and previewUrl for a preview.

Projects written in Syntext

•
One revision per call. Everything a call changes (a moved page, its sidebar entry and its redirect, say) lands in one revision, recorded as made through MCP by you, so it shows in the project's history and can be restored like any other.
•
Conflicts. expectedSha works the same as on GitHub: if the file changed since you read it, nothing is saved.
•
Limits. A project holds at most 2,000 files and 200 MB; a change past either is refused and nothing is saved. Paths follow the project's rules: pages at the top level (not directly in docs/), no hidden folders, and .md, .mdx, .json and .yaml text files, custom code files in _syntext/, plus images from upload_image.
•
Publishing. mode: "commit" publishes the project as Publish in the dashboard does, counting toward the plan's builds — and, like Publish, it ships every unpublished draft too, whoever saved it. When the builds are used up, the revision is kept and buildError says it publishes with the next build. Use mode: "draft" to save without publishing.
•
Refused, because a project written in Syntext has no branches: mode: "pull_request" on any tool, and preview_build. The error suggests mode: "draft" to save without publishing, or mode: "commit" to save and publish.
•
Approval gates still apply: a commit a gate holds back is refused — including one that would publish someone else's draft of a gated page — and the error suggests mode: "draft". A workspace owner, or a role the gate auto-approves, can publish.

Paths are relative to the docs root. They can't contain .., hidden (.-prefixed) folders, a leading /, empty segments, %, ?, # or \.

edit_page

Edit page. Changes part of a file with exact find-and-replace edits and leaves the rest as it is — cheaper and safer than sending a whole page back with update_page. Works on .md and .mdx pages, syntext.json, _meta.json and custom code files in _syntext/.

ArgumentTypeRequiredDescription
project, pathstringYesThe file must exist
editsarrayYes1–50 { "oldText", "newText" }, applied in order, each to the result of the one before. newText may be empty to delete
expectedShastringNoThe sha from get_page_source. If the file changed since, nothing is saved
modestringNocommit (default), draft or pull_request
changeIdstringNoAdd this write to an unpublished change ("draft" or "pr-<number>") instead; see Adding to a change
messagestringNoCommit message, revision note or pull request title

Each oldText has to occur exactly once in the file. If one matches nowhere, or in several places, nothing is saved and the error names the edit and the count, so you can include more of the surrounding text. An edit that leaves the file unchanged is refused too.

json
{
"project": "acme",
"path": "guides/quickstart.mdx",
"edits": [{ "oldText": "npm install acme", "newText": "npm install @acme/sdk" }],
"mode": "draft"
}

create_page

Create page. Creates a new page. Refuses if the file exists.

ArgumentTypeRequiredDescription
projectstringYes
pathstringYesEnds in .mdx or .md
contentstringOne of content, titleThe full MDX, with frontmatter, up to 1 MB
titlestringWithout content, the page is a scaffold: frontmatter with this title and a heading
navGroupstringNoAdd the page to this sidebar group, in the same commit
modestringNocommit (default), draft or pull_request
changeIdstringNoAdd this write to an unpublished change ("draft" or "pr-<number>") instead; see Adding to a change
messagestringNoCommit message, revision note or pull request title
Note

On the hosted connector create_page used to be another name for generate_page_template. It now creates pages; a call with only pageType and title is refused with a message naming the missing project and path. The local MCP server still calls its template tool create_page.

update_page

Update page. Replaces one file with content as its full new text, creating it if it doesn't exist. It writes .md and .mdx pages, syntext.json, _meta.json and custom code files in _syntext/, and nothing else.

ArgumentTypeRequiredDescription
projectstringYes
pathstringYes
contentstringYesUp to 1 MB
expectedShastringNoThe sha from get_page_source. If the file changed since, nothing is saved
modestringNocommit (default), draft or pull_request
changeIdstringNoAdd this write to an unpublished change ("draft" or "pr-<number>") instead; see Adding to a change
messagestringNo

Custom code files

update_page and edit_page can write the files of your _syntext/ folder: a .css file, a .js file or head.html, directly in _syntext/ (for example "path": "_syntext/style.css").

•
CSS follows the same rules as pages: anyone who can write pages can write it.
•
Scripts and head.html are written only for workspace admins and owners. For anyone else: Only workspace admins can change scripts and head tags in _syntext/. Ask an admin, or put styles in a .css file.
•
Content is checked like a publish. A file that breaks a rule is refused with Nothing was saved: and the reason, such as _syntext/style.css: CSS may load only https:// URLs (found "http://…").
•
Other files in _syntext/, and files in subfolders of it, are refused.
•
The switches stay as they are. The connector can't turn Head tags from your docs or Scripts from your docs on — a workspace admin does that in Integrations › Custom code — and a draft or pull request preview never runs scripts or head.html.

move_page

Move or rename page. In one change (commit, revision or pull request): the page is written at to and removed at from, its sidebar entry points at the new path, and — when the old URL is live — a redirect from it to the new one is added to redirects in syntext.json (see redirects). Refuses if from doesn't exist or to does.

With changeId, the move happens inside that unpublished change, so it can move a page that exists only there (one you just created in the same pull request or draft, say). A page that was never live gets no redirect.

ArgumentTypeRequiredDescription
project, from, tostringYesPage paths ending in .mdx or .md
addRedirectbooleanNoAdd a redirect from the old URL when it is live. Default true
modestringNocommit (default), draft or pull_request
changeIdstringNoAdd this write to an unpublished change ("draft" or "pr-<number>") instead; see Adding to a change
messagestringNo

Returns navigationUpdated and the redirect added (or null).

delete_page

Delete page. Removes one .mdx or .md page in one change, together with its sidebar entries — in syntext.json navigation and in the folder's _meta.json. With redirectTo, the deleted URL redirects to that path, added to redirects in syntext.json (see redirects) — only when the page was live, since a page that was never published has no URL to keep.

Deleting is the one write that loses content, so it defaults to mode: "draft": a pull request on a GitHub project, an unpublished revision on a project written in Syntext. Review it with diff_changes, then publish_changes. With mode: "commit" it saves and publishes, and the page leaves the live site when that build completes.

With changeId, the delete happens inside that unpublished change, so it can remove a page that exists only there (one you created earlier in the same pull request or draft, say).

It refuses, and saves nothing, for:

•
syntext.json, _meta.json and any file that isn't a page — change the sidebar with update_navigation;
•
the home page (index.mdx) — replace its content with update_page or edit_page instead;
•
a path that doesn't exist (the error names an unpublished change that has it, if there is one);
•
a redirectTo that isn't a path on the site (a full URL to another site, say) or that points at the page being deleted.
ArgumentTypeRequiredDescription
project, pathstringYesThe page to delete, e.g. guides/old.mdx
modestringNodraft (default), pull_request (GitHub projects) or commit
changeIdstringNoDelete inside this unpublished change ("draft" or "pr-<number>"); see Adding to a change
removeFromNavigationbooleanNoRemove the page's sidebar entries. Default true
redirectTostringNoPath to redirect the deleted URL to, e.g. /guides/new. Added only when the page was live
messagestringNo

Returns path, removedFromNavigation (true when a sidebar entry was removed) and the redirect added (or null).

update_navigation

Update navigation. Applies operations in order to the navigation array of your site config, all or nothing, and commits the file with every other key, its order and formatting kept (YAML comments too). Pages stay on disk.

opFieldsEffect
add_pagepage, group, position?Adds a page reference (guides/auth, no extension) to a group
remove_pagepageRemoves every reference to the page
move_pagepage, group, position?Moves the reference to another group
add_groupgroup, tab?, position?Adds an empty group, optionally under a header tab
rename_groupgroup, toRenames a group
remove_groupgroupRemoves a group and its references

Group names match exactly, then ignoring case; nested groups count. position is zero-based; the default is last. Up to 50 operations. A missing group or page, or a duplicate, refuses the whole call with a message naming it.

Besides project and operations, it takes mode (commit by default, draft or pull_request), changeId to add the edit to an unpublished change (Adding to a change), and message.

json
{
"project": "acme",
"operations": [
{ "op": "add_group", "group": "Webhooks", "position": 2 },
{ "op": "add_page", "page": "guides/webhooks", "group": "Webhooks" }
],
"mode": "pull_request"
}

add_changelog_entry

Add changelog entry. Puts an <Update> block above the newest entry on the changelog page, or creates the page with it.

ArgumentTypeRequiredDescription
project, title, bodystringYesbody is MDX, up to 50,000 characters
datestringNoThe entry's label, default today, e.g. 14 November 2026
tagsstring[]NoUp to 10
pathstringNoDefault changelog.mdx
modestringNocommit (default), draft or pull_request
changeIdstringNoAdd this write to an unpublished change ("draft" or "pr-<number>") instead; see Adding to a change

Use draft_changelog first to draft the entry from recent changes.

upload_image

Upload image. Adds one image to the project's docs and returns the path to use in MDX, /images/<filename>, with a ready-made mdx reference such as ![Webhook flow](/images/webhooks/flow.png).

ArgumentTypeRequiredDescription
projectstringYes
filenamestringYesFile name, optionally in folders under images/, e.g. webhooks/flow.png
datastringYesThe image bytes, base64-encoded
mimeTypestringYesimage/png, image/jpeg, image/gif, image/webp or image/svg+xml. Must match the file extension
altstringNoAlt text for the returned reference, up to 300 characters. Default: the file name
modestringNocommit (default) saves the image without publishing the site. draft saves it unpublished (a pull request on GitHub, the draft of a project written in Syntext); pull_request opens a pull request (GitHub projects only)
changeIdstringNoAdd the image to this unpublished change, so a page drafted there can show it in its preview. See Adding to a change
messagestringNoCommit message, revision note or pull request title
•
Limits. Up to 2 MB per image (SVGs up to 512 KB). Each file is checked as dashboard uploads are: its contents must match its type, and SVGs are cleaned of scripts and external references (sanitized: true).
•
Never replaces. If a file with that name exists with different contents, nothing is saved; choose another name. The same bytes again return alreadyPresent: true.
•
Where it goes. On a project written in Syntext the image is saved with the project; on a GitHub project it is committed at public/images/<filename>. Either way it is served at /images/<filename>.
•
Not published on its own. The image is saved but reaches the live site with the next build, such as the one that publishes a page using it, so published is always false.

draft_page_from_gap

Draft page from a docs gap. Saves a new page for a gap from get_docs_gaps without publishing it: an unpublished revision on a project written in Syntext (change "draft"), a pull request on a GitHub project.

ArgumentTypeRequiredDescription
project, pathstringYespath must not exist
gapIdstringYesThe gap id
titlestringNoDefault: the gap topic
contentstringNoYour MDX. Without it, the draft is an outline: a note that it is a draft, the questions readers asked, links to related pages, and headings to fill in
changeIdstringNoAdd the draft page to this unpublished change instead of starting a new one

Visitors' questions are escaped before they go into the page, so they can't add components or code, and they are never put in the pull request description.

fix_deprecated_syntax

Fix deprecated syntax. Finds deprecated Syntext syntax in a project's files — config keys, frontmatter keys, MDX tags and props, and on doc engine v2 the generated docs home — and rewrites it, as stx migrate and the dashboard's Fix automatically do.

•
A dry run by default. It returns each file's diff, every rewrite (old form → replacement, with file and line), what it leaves unchanged and why, and saves nothing.
•
With dryRun: false the rewrites are saved as one unpublished change: a draft on a project written in Syntext, a pull request on a GitHub project — or more commits on the change changeId names. It never commits to your production branch or publishes; publish the change with publish_changes.
•
Doc engine v2. v2: true also moves colors, fonts and style flags into appearance, which switches a v1 site to doc engine v2 and changes its look. Without it those forms are listed under notRewritten with requiresV2: true.
•
Nothing to fix is a normal result with the note "No deprecated syntax found."
ArgumentTypeRequiredDescription
projectstringYes
dryRunbooleanNoReturn the diff without saving. Default true
v2booleanNoAlso apply the moves into appearance, switching a v1 site to doc engine v2. Default false
modestringNodraft (default): a draft, or a pull request on GitHub. pull_request: a pull request (GitHub projects only). There is no commit
changeIdstringNoAdd the fix to this unpublished change ("draft" or "pr-<number>"); see Adding to a change

Returns source (github or hosted), switchesToV2, files (each path and unified diff; past 60,000 characters of diffs, the rest are listed with truncated: true), rewritten, notRewritten, remaining (what the build would still report), home (converted, or why not), notes and published: false. A saved fix adds mode, changeId and reviewUrl, plus pullRequestUrl, pullRequestNumber and previewUrl for a pull request or revision for a draft. A dry run, or nothing to rewrite, returns unchanged: true. The same fix is available over the API: Fix Deprecated Syntax.

suggest_edit

Suggest an edit. Proposes a change to a page without publishing it, for the project's owners to accept or discard: an unpublished revision on a project written in Syntext, a pull request on a GitHub project. Returns the changeId, suggested: true and a reviewUrl — the pull request, or the editor where the unpublished changes are.

ArgumentTypeRequiredDescription
project, pathstringYes
summarystringYesWhat the suggestion changes and why, up to 200 characters. Used as the revision note or pull request title
editsarrayOne of edits, contentExact find-and-replace edits, as in edit_page
contentstringThe full new text of the file instead, up to 1 MB
changeIdstringNoAdd the suggestion to this unpublished change. Only a pull request the connector opened, or "draft"

request_review

Request a review. Asks workspace members to review an unpublished change. Each reviewer gets a review request in the project's Workflow › Reviews list in the dashboard (see Reviews), with the diff attached and, for a GitHub change, the pull request linked. Publishes nothing. Returns reviewRequests (id, reviewer, status) and the reviewUrl.

ArgumentTypeRequiredDescription
project, changeIdstringYes
reviewersstring[]Yes1–10 email addresses. Each must belong to a member of the project's workspace, and you can't review your own change
titlestringNoDefault: the change's title
notestringNoWhat to look at, up to 5,000 characters

If a reviewer isn't a member of the workspace, nothing is requested and the error lists up to 10 members who can review (Name <email>), so you can pick one. Invite anyone else from the workspace settings in the dashboard.

publish_changes

Publish changes. Puts an unpublished change on the live site and starts a build, counting toward the plan's builds.

•
Written in Syntext ("draft"): publishes every saved edit not yet live, whoever made it — as Publish in the editor does.
•
GitHub ("pr-<number>"): squash-merges the connector's pull request into the production branch, deletes its branch, then builds. If the build can't start, the pull request stays merged and buildError says it publishes with the next build.

Approval gates apply: if a gate holds back any page in the change, nothing is published and the error says who can publish it. Returns changeId, published, buildId, and files and revision or commitSha and branchDeleted.

ArgumentTypeRequiredDescription
project, changeIdstringYes
messagestringNoRevision note or merge commit message

discard_changes

Discard changes (close the pull request). Throws an unpublished change away. The live site doesn't change.

•
GitHub ("pr-<number>"): the connector's pull request is closed and its branch deleted. Pull requests people opened themselves are refused: close those on GitHub.
•
Written in Syntext ("draft"): the draft is dropped — every saved edit not yet live is put back to the published version, as a new revision, so the history keeps what was discarded and it can be restored.
ArgumentTypeRequiredDescription
project, changeIdstringYes

preview_build

Build a preview. Builds a branch other than the production branch, such as a pull request branch, as a preview at its own URL. Returns buildId, status, preview: true, branch and previewUrl. Counts toward the plan's builds. GitHub projects only: a project written in Syntext has no branches, so it is refused.

ArgumentTypeRequiredDescription
project, branchstringYesThe branch must exist in the repository, and can't be the production branch

trigger_build

Publish site. Builds the production branch, or the current revision of a project written in Syntext, and replaces the live site when the build succeeds. Returns { buildId, status, preview: false }; follow it with get_build_status. Refused for a project published with stx deploy. Counts toward the plan's builds and is recorded against you.

Authoring tools

These five tools don't read your account: they describe Syntext's MDX and check it. They are also in the local MCP server.

get_components

Returns every Syntext MDX component with its props and a worked example. Use it before writing any page, so the assistant reaches for <Steps> and <CodeGroup> rather than inventing markup that will not compile.

ParameterTypeRequiredDescription
namestringNoA single component, e.g. Card or CodeGroup. Omit for all of them.
categoryenumNoOne of layout, home, navigation, code, callouts, interactive, api, media, steps. A component can be in more than one: Hero is in layout and home, SearchBar in home and navigation.

Asking for an unknown name is not an error — the tool replies with the list of components that do exist, so the assistant can correct itself without another round trip.

text
"Show me every callout component Syntext supports."

home returns what a docs home is built from: Hero with title, SearchBar and the eight home blocks, from SectionCards to SupportCard. Most of them fill themselves from the site when written empty and self-closing, such as <SectionCards />.

get_frontmatter

Returns the frontmatter schema: which keys exist, which are required, what each accepts, and an example block.

ParameterTypeRequiredDescription
pageTypeenumNoOne of guide, api-reference, changelog, landing, sdk. Omit for the full schema.

landing is the docs home, index.mdx. Its example uses layout: wide, and it's followed by the whole starter index.mdx — the one generate_page_template returns, plus a Get started link to /quickstart. It shows home as deprecated: the generated home ended on 16 November 2026, so home is ignored and the index shows its own content. The local server (@syntext/mcp 0.2.0 and later) shows the same.

Every page needs frontmatter with at least a title. Passing pageType narrows the answer to the fields that page type actually uses, which keeps the assistant from adding keys that do nothing.

text
"What frontmatter does an api-reference page need?"

get_config

Returns the syntext.json schema — site metadata, navigation, theming (theme and themeOverrides) and the structural feature flags — or a complete example config to start from.

ParameterTypeRequiredDescription
exampleenumNofull for a config exercising every key, minimal for the smallest working one. Omit for the schema itself.
Note

The legacy filenames syntext.config.json and stx.json are still accepted. New projects should use syntext.json.

text
"Give me a minimal syntext.json to start from."

validate_mdx

Checks a block of MDX and reports errors and warnings, each with a line number and — where one exists — a concrete suggestion for the fix.

ParameterTypeRequiredDescription
contentstringYesThe MDX content to validate.

Errors are things that will fail the build. Warnings are things that will build but read badly — a missing description, a heading level skipped. An assistant that calls this before writing a file catches both while it can still fix them.

Components with no children can be self-closing (<SectionCards />). home frontmatter gets a warning — the generated home ended on 16 November 2026, so it's ignored — while home: false doesn't. The local server (0.2.0 and later) does the same.

text
"Validate this page before we commit it."

generate_page_template

Returns a complete page template as text — it saves and publishes nothing: correct frontmatter for the page type, a sensible heading structure, and the components that page type usually wants.

ParameterTypeRequiredDescription
pageTypeenumYesOne of guide, api-reference, quickstart, landing.
titlestringYesThe page title.
descriptionstringNoThe page description. A placeholder is used if omitted.

landing returns the doc engine v2 home starter:

mdx
---
title: Acme Docs
description: Guides and answers, in one place.
layout: wide
---
<Hero title="Acme Docs" description="Guides and answers, in one place.">
<SearchBar mode="both" />
</Hero>
<SectionCards />
<LatestUpdates count={3} />

Templates link to no other page, since your site may not have the pages a link would point at — a guide's Next steps cards have placeholder text and no href, and the landing hero has no Get started link. Add links to pages your site has.

The template is a starting point, not a finished page — it is scaffolding with the structural decisions already made correctly.

text
"Create a guide page called 'Webhook Signatures'."

On the local MCP server this tool is called create_page. The hosted connector lists it as generate_page_template and still accepts create_page.

A typical authoring loop

  1. 01Step 1 of 41 ›Step 11.
    Learn the surface

    The assistant calls get_components and get_frontmatter once, so it knows what it is allowed to write.

  2. 02Step 2 of 42 ›Step 22.
    Scaffold

    generate_page_template (create_page on the local server) produces the skeleton with correct frontmatter for the page type.

  3. 03Step 3 of 43 ›Step 33.
    Write

    The assistant fills in the body using components it has seen the real props for.

  4. 04Step 4 of 44 ›Step 44.
    Check

    validate_mdx catches anything that will not compile, before the file is written.

Run stx check afterwards for the same validation over the whole project, including link resolution across pages, which a single-page tool cannot see.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext