How to create and publish documentation with AI and MCP

AI assistants have gotten very good at answering questions from documentation. Point a model at your docs and it can summarize, explain, and troubleshoot with surprising accuracy.

Writing documentation is a different problem. To write a page that actually belongs in your docs, an AI tool needs to know how your existing docs sound, how they’re organized, what terminology you use — and then it needs a way to get the finished draft into your docs platform. That’s exactly the gap the Model Context Protocol (MCP) closes.

In this walkthrough, we’ll use GitBook’s MCP server to turn an internal spec into a published documentation page.

A quick reminder: what is MCP?

MCP is an open standard, originally introduced by Anthropic, that lets AI applications talk to outside systems in a structured way. There are two important roles when working with MCP:

• An MCP server exposes data and actions — think of it as an API designed for language models. It can offer readable resources (such as your docs pages), callable tools (including create a page, open a change request), and reusable prompts.

• An MCP client is the AI application on the other end — Claude, Claude Code, Cursor, VS Code with Copilot, and similar tools — which queries servers for context and invokes their tools on your behalf.

GitBook sits on both sides of the writing workflow: it serves your published content to AI tools, and it accepts edits back from them.

GitBook’s two MCP servers

This is where GitBook’s setup differs from most docs platforms: you don’t just get one server, you get two, and they play different roles.

1. The published docs server (read-only). Every published GitBook site automatically exposes its own MCP server at {your-docs-url}/~gitbook/mcp. This server lets AI tools search and read the latest published version of your site — while draft content stays private. This is the server that teaches the AI your voice, structure, and terminology.

2. The GitBook MCP server (read/write). Hosted at https://mcp.gitbook.com/mcp, this server connects to the GitBook API itself. Through it, an AI tool can create pages, draft content, open change requests, restructure spaces, and configure sites. It authenticates with OAuth or a personal access token, so the AI only touches what your account can touch. GitBook’s MCP server is loaded with skills, so the MCP client understands the best ways to use GitBook’s components and features.

The scenario

Imagine you work at Acme and you’re shipping a new product feature. Engineering has written a solid spec in a pull request or internal reference, but there’s no customer-facing docs page yet. Here’s how to create it with GitBook:

1. Connect your docs’ MCP server so the AI can absorb your style and check for overlap with existing pages

2. Connect the GitBook MCP server so the AI can write the result back

3. Hand the AI your spec and iterate on a draft in a conversation

4. Open a change request in GitBook with your AI agent. Then, review and publish.

Step 1: Connect your published docs server

First, wire up the read-only server for your own site so the AI has your existing docs as context.

In Claude, go to Settings → Connectors → Add custom connector and paste your site’s MCP URL:

<https://docs.acme.com/~gitbook/mcp>

<https://docs.acme.com/~gitbook/mcp>

<https://docs.acme.com/~gitbook/mcp>

<https://docs.acme.com/~gitbook/mcp>

In Claude Code, it’s one command:

claude mcp add --transport http acme-docs <https://docs.acme.com/~gitbook/mcp>

claude mcp add --transport http acme-docs <https://docs.acme.com/~gitbook/mcp>

claude mcp add --transport http acme-docs <https://docs.acme.com/~gitbook/mcp>

claude mcp add --transport http acme-docs <https://docs.acme.com/~gitbook/mcp>

Cursor and VS Code work the same way — just add the URL to their MCP settings.

Step 2: Connect the GitBook MCP server

Next, add the editing server so edits can flow back into GitBook:

claude mcp add --transport http gitbook <https://mcp.gitbook.com/mcp>

claude mcp add --transport http gitbook <https://mcp.gitbook.com/mcp>

claude mcp add --transport http gitbook <https://mcp.gitbook.com/mcp>

claude mcp add --transport http gitbook <https://mcp.gitbook.com/mcp>

You’ll sign in via OAuth the first time (or supply a personal access token). With both servers connected, your AI tool can now read your published docs and complete actions in your GitBook organization.

Step 3: Draft the page in conversation

Paste in the new feature’s specification and ask for a first draft:

“Using the tone, structure, and terminology of the Acme docs, write a documentation page for the new product feature described in this spec.”

Because the AI can query your published docs server live, the draft content won’t read like generic AI output — it will pick up your heading conventions, your naming, and your level of technical depth. From there, your can iterate the way you would with a colleague:

• “Check whether any of this duplicates our existing performance-tuning page.”

• “Add a troubleshooting section matching the format we use elsewhere.”

• “Tighten the intro — our pages usually open with a one-sentence definition.”

Each request triggers fresh lookups against your real docs, so the feedback loop stays grounded in what’s actually published.

Step 4: Publish to GitBook with GitBook’s MCP

When the draft content is ready, ask the AI to push it into GitBook via the MCP server. It will create the new page in the right space and open a change request. Your team can then review the change request in GitBook as usual. When it’s ready, merging it publishes the page.

There’s no copy-pasting markdown between windows and no need for extra steps. The same conversation that wrote the page also ships it.

Why this beats the old way

You could always paste docs into a chatbot and paste the answer back out. It worked, but you lost context between turns, the model couldn’t see the rest of your docs to match your style, and every revision meant another round of manual shuttling.

With MCP servers on both ends, documentation writing becomes a genuinely iterative loop: the AI keeps live access to your whole published site while drafting, and it has a permission-based path to write changes back. The human role shifts from creator to editor — you review change requests instead of assembling pages by hand.

What to try next

Both servers are available today: the published docs server is generated automatically for every GitBook site, and the GitBook MCP server works with any client that supports remote MCP over HTTP.

Start small — connect your docs server and ask the AI to audit a page for outdated content — then graduate to full spec-to-published-page workflows once you trust the loop.

→ MCP explained: What is an MCP server and why it matters for documentation

→ What we learned building a complete docs site using Claude, MCP and skill.md

→ Supporting AI standards at GitBook: What OKF, MCP and llms.txt tell us about the future of docs