<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[DocStar Blog]]></title><description><![CDATA[AI-ready docs for developers. DocStar turns your API docs into an MCP server, a CLI and a help center your AI agent can manage. docstar.io]]></description><link>https://docstar-blog.hashnode.dev</link><image><url>https://cdn.hashnode.com/uploads/logos/6af69d5e3b0c53da1c3330a9/7fcafdd0-08da-48a5-8565-c30f84fe67ad.png</url><title>DocStar Blog</title><link>https://docstar-blog.hashnode.dev</link></image><generator>RSS for Node</generator><lastBuildDate>Mon, 16 Nov 2026 21:32:28 GMT</lastBuildDate><atom:link href="https://docstar-blog.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[How to Write a Setup Guide AI Agents Can Follow]]></title><description><![CDATA[What a setup guide for AI agents needs: call order, rules, confirm-first actions and checks, and how coding agent writes and maintains it in DocStar.]]></description><link>https://docstar-blog.hashnode.dev/how-to-write-a-setup-guide-ai-agents-can-follow</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/how-to-write-a-setup-guide-ai-agents-can-follow</guid><category><![CDATA[ai agents]]></category><category><![CDATA[#ai-tools]]></category><category><![CDATA[AI Tools for Developers]]></category><category><![CDATA[mcp]]></category><category><![CDATA[mcp server]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Mon, 16 Nov 2026 13:14:15 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/8f63d2ed-564d-43eb-bc75-42af5a0b1ec4.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>With DocStar, every API you document gets a setup guide that AI agents read before they touch your API: the skill that ships with your collection's MCP server. A setup guide for AI agents is a short, ordered set of instructions an agent can follow on its own: what your product is for, which steps to run in which order, what to ask the human, what never to do, and how to confirm it worked. Human quickstarts explain; agent setup guides instruct.</p>
<p>This post shows what a good agent setup guide contains, and how to have your own coding agent write it, publish it and keep it current in DocStar, so you review the result instead of writing it from scratch.</p>
<h2>Why AI agents need a different kind of setup guide</h2>
<p>A human skims your quickstart and clicks around until something works. An agent takes your words literally, fetches several pages to fill gaps and guesses when the order of calls isn't written down. If a step needs a human (signing in, approving access), it may stall or try to work around it.</p>
<ul>
<li><strong>Goal:</strong> Human quickstart: Explain the product and build confidence; Setup guide for AI agents: Get a task done correctly, first time</li>
<li><strong>Format:</strong> Human quickstart: Narrative, screenshots, tips; Setup guide for AI agents: Short ordered steps and rules</li>
<li><strong>Decisions:</strong> Human quickstart: "Choose what fits you"; Setup guide for AI agents: Explicit branches: "if X, do Y"</li>
<li><strong>Human steps:</strong> Human quickstart: Implied; Setup guide for AI agents: Named: "stop and ask the user to..."</li>
<li><strong>Safety:</strong> Human quickstart: Rarely stated; Setup guide for AI agents: Which actions are safe, which need confirmation</li>
<li><strong>Done check:</strong> Human quickstart: "You should see..."; Setup guide for AI agents: A call or check the agent can run itself</li>
<li><strong>Reply to the user:</strong> Human quickstart: Not covered; Setup guide for AI agents: What to say, in two or three sentences</li>
</ul>
<p>In DocStar you don't maintain two sets of docs: the same collection serves your human docs, the agent setup guide, the tools and the Markdown agents read.</p>
<h2>What a good agent setup guide contains</h2>
<p>Whether you write it yourself or have an agent draft it, a setup guide agents can follow covers seven things:</p>
<ol>
<li><strong>What the API is for</strong>, in two or three sentences. Agents use this to decide whether your tools are the right ones for the user's request.</li>
<li><strong>The usual order of calls.</strong> "List projects, then create a task in a project." "Call Create Customer before Create Invoice." This is the single most useful line you can write.</li>
<li><strong>How ids relate.</strong> Where an <code>account_id</code> comes from, which call returns the <code>project_id</code> the next call needs.</li>
<li><strong>Rules and limits.</strong> Required fields, rate limits, formats, versions to use.</li>
<li><strong>Safe vs. confirm-first actions.</strong> Reading is fine; deleting, sending or charging needs the user's yes.</li>
<li><strong>What only a human can do.</strong> Signing in, approving OAuth consent, entering secrets. The agent should stop and ask, not improvise.</li>
<li><strong>Common mistakes and how to check success.</strong> The errors agents hit most, and one call that proves the setup worked.</li>
</ol>
<p>Keep it short: every line should change what the agent does.</p>
<h2>How DocStar gives your API a setup guide agents read first</h2>
<p>Every DocStar collection has its own hosted MCP server, and every MCP server ships with a <strong>skill</strong>: a short quickstart guide that assistants load before they use your API. That skill is your agent setup guide. Here's what DocStar gives you around it, as described in <a href="https://docstar.io/help/mcp/collection-mcp-server">Build an MCP Server for Your App</a>:</p>
<ul>
<li><strong>Generated skill:</strong> What it does for agents: DocStar writes the skill from your docs and keeps it following your docs and tools as they change.</li>
<li><strong>Your own skill:</strong> What it does for agents: Write it when you know things the docs don't say: call order, how ids relate, common mistakes. Reset it any time to go back to the generated one.</li>
<li><strong>Additional instructions:</strong> What it does for agents: Short rules assistants receive every time they connect, such as "Ask for the account id before creating an order". Keep them under 2,000 characters.</li>
<li><strong>Endpoint tools:</strong> What it does for agents: Up to 20 of your most important endpoints as named tools, with safety hints (read-only, destructive, idempotent, open-world) so assistants know when to ask first.</li>
<li><strong>Sign-in for API calls:</strong> What it does for agents: Users call your API with their own account; the assistant asks them to sign in the first time.</li>
<li><strong>llms.txt and Markdown pages:</strong> What it does for agents: DocStar generates llms.txt and a Markdown copy of every published page (add <code>.md</code> to the URL), so a setup page in your docs is easy for agents to fetch.</li>
</ul>
<p>We use the same pattern ourselves. When you ask an assistant to build an MCP server with DocStar, the prompt points it at <code>https://docstar.io/mcp/quickstart.md</code>, a single page written for agents to follow step by step.</p>
<p>Only published content reaches your MCP server; drafts never do.</p>
<h2>Let your coding agent write the setup guide</h2>
<p>DocStar is built to be run by AI agents. Your coding agent can read your code and your DocStar docs at the same time, which makes it better placed than anyone to write the setup guide. Here's the main path.</p>
<h3>Step 1: Connect your agent to DocStar</h3>
<p>Add DocStar to Claude Code, Cursor, Codex or another assistant. Use DocStar from your assistant's connector directory if it's listed; if not, add it as a custom remote MCP server:</p>
<pre><code class="language-text">https://mcp.docstar.io/mcp
</code></pre>
<p>The first time the agent needs your workspace, you sign in to DocStar in your browser. There's no API key to copy. Full steps: <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect Your AI Assistant</a>.</p>
<h3>Step 2: Give it one prompt</h3>
<p>Open your API's repository in the agent and paste:</p>
<blockquote>
<p>Use the DocStar MCP. First read <a href="https://docstar.io/mcp/quickstart.md">https://docstar.io/mcp/quickstart.md</a> and follow it. Then write the MCP skill for my API collection "YOUR COLLECTION NAME" as a setup guide for AI agents. Read my latest code, not old docs. Cover: what the API is for in 2-3 sentences, the usual order of calls, how ids flow between calls, required fields and limits, which endpoints are safe to call freely and which need the user's confirmation, what only the user can do (like signing in), the most common errors and one call that proves setup worked. Keep it short. Also suggest short additional instructions for rules that must always apply. Show me both before you save anything.</p>
</blockquote>
<h3>Step 3: Let the agent do the work</h3>
<p>From that one prompt, the agent:</p>
<ul>
<li>Reads your routes, handlers and validation to find the real order of calls and the ids each call needs.</li>
<li>Reads your DocStar collection to see which endpoints are documented and published.</li>
<li>Drafts the skill and a short set of additional instructions.</li>
<li>Suggests named tools and safety hints (for example, <code>delete_invoice</code> as destructive).</li>
<li>Shows you everything and asks before it changes or publishes anything.</li>
</ul>
<p>A skill it writes might start like this:</p>
<pre><code class="language-markdown"># Acme Billing API: setup guide for agents
Acme Billing creates customers, invoices and payments.
Order: create_customer -&gt; create_invoice (needs customer_id) -&gt; send_invoice.
Always list_customers first; never create a duplicate customer for the same email.
Safe: list_*, get_*. Confirm with the user first: send_invoice, delete_invoice, refund_payment.
The user must sign in the first time you call the API. If a call returns 401, ask them to sign in again.
Setup check: list_customers returns 200.
</code></pre>
<h3>Step 4: You review and decide</h3>
<p>Your role is judgment, not typing:</p>
<ul>
<li><strong>Accuracy.</strong> Is the call order right? Are the limits current?</li>
<li><strong>Safety.</strong> Is every destructive action marked confirm-first?</li>
<li><strong>What stays private.</strong> Internal endpoints and admin-only flows don't belong in a public setup guide.</li>
<li><strong>The few human-only steps.</strong> If users should call your API with their own account, you enter your OAuth app's details in the collection's MCP tab yourself.</li>
</ul>
<p>Then tell the agent to save, and publish the docs it drafted.</p>
<h2>Publish a setup page agents can fetch directly</h2>
<p>Some agents never connect to your MCP server: a developer pastes your docs link into a coding agent, or an assistant browses your site. Give them a setup page too.</p>
<p>Ask your agent:</p>
<blockquote>
<p>Using the DocStar MCP, create a page called "Setup for AI agents" in my docs collection with the same steps as the skill, written for agents: numbered steps, explicit if/then branches, what to ask the user, and a final check. Save it as a draft.</p>
</blockquote>
<p>Once you publish it, DocStar serves a Markdown copy at the page URL plus <code>.md</code>, and lists it in your generated llms.txt, which links to those Markdown versions. See <a href="https://docstar.io/help/publish-and-seo/seo">SEO, Sitemap and llms.txt</a>.</p>
<p>If your docs live in your repo, the agent can write the page in your <code>docs/</code> folder instead, and <a href="https://docstar.io/help/integrations/github-sync">GitHub Sync</a> sends it to DocStar on push.</p>
<h2>Keep it current</h2>
<p>An outdated setup guide is worse than none: the agent follows it confidently and fails.</p>
<p><strong>Let the generated skill do the work where it can.</strong> If you don't need custom guidance, keep DocStar's generated skill. It follows your docs and tools as they change. Endpoint tools with an empty description also follow the endpoint's docs.</p>
<p><strong>Update docs in the same change as the code.</strong> With GitHub Sync, your OpenAPI files in <code>api-docs/</code> live next to the code, so they change in the same commit and pull request, and spec changes show up in the PR diff. Add <code>docstar.md</code> and one line in <a href="http://AGENTS.md">AGENTS.md</a>, and your coding agent updates the endpoint's spec whenever it changes the endpoint. On push, the GitHub Action publishes the change to your docs site, MCP tools and CLI. The agent still has to do it: if someone changes code without an agent, or the agent skips the rule, docs can drift. More on that in <a href="https://docstar.io/blog/what-is-agents-md">What Is AGENTS.md?</a></p>
<p><strong>Refresh your custom skill when the flow changes.</strong> Once you write your own skill, it no longer follows doc changes, so add it to your release routine:</p>
<blockquote>
<p>Using the DocStar MCP, compare my collection's MCP skill and the "Setup for AI agents" page with the current code and published docs. List anything that's wrong or missing, then propose updated text. Don't save until I approve.</p>
</blockquote>
<p><strong>Use the logs as feedback.</strong> In the MCP tab, <strong>Logs</strong> shows every call assistants made to your API through your MCP server, with the request, the response and a one-line reason when it failed. Repeated <code>404</code>s mean agents are using wrong paths or ids; <code>400</code> or <code>422</code> means the body was wrong. Each pattern is a line your setup guide is missing. Calls are kept for two weeks.</p>
<h2>Prefer to write it yourself?</h2>
<p>Open your collection's settings, go to the <strong>MCP</strong> tab, and edit the skill and additional instructions there, using the seven-point checklist above. Good tool descriptions matter as much as the skill; see <a href="https://docstar.io/blog/write-mcp-tool-descriptions">How to Write MCP Tool Descriptions That AI Agents Actually Understand</a>.</p>
<h2>Why teams choose DocStar</h2>
<ul>
<li><strong>One source, every reader.</strong> The same collection powers your docs site, llms.txt, Markdown copies, your MCP server and its skill, and a CLI.</li>
<li><strong>A setup guide by default.</strong> Every MCP server ships with a generated skill, so agents get guidance from day one.</li>
<li><strong>Control where it matters.</strong> Custom skill, instructions, named tools with safety hints, and per-user sign-in.</li>
<li><strong>Agent-first workflow.</strong> Your coding agent drafts it all through the DocStar MCP; you review and publish.</li>
</ul>
<h2>FAQ</h2>
<p><strong>What is a setup guide for AI agents?</strong> A short set of ordered instructions an agent follows on its own to set up or use your product: purpose, call order, rules, safe vs. confirm-first actions, human-only steps and a success check. In DocStar it's the skill your MCP server ships with.</p>
<p><strong>Does DocStar write the skill for me?</strong> Yes. DocStar generates a skill from your docs, and it follows your docs and tools as they change. You can write your own at any time and reset to the generated one later.</p>
<p><strong>What's the difference between the skill and additional instructions?</strong> The skill is longer guidance assistants load before using your API. Additional instructions are short rules, under 2,000 characters, assistants receive every time they connect.</p>
<p><strong>Can agents that don't use my MCP server read the guide?</strong> Yes, if you publish it as a page. DocStar serves a Markdown copy of every published page and lists pages in your llms.txt.</p>
<h2>Get started free</h2>
<p>Give your API a setup guide AI agents can follow, written by your own coding agent and kept next to your docs. <a href="https://app.docstar.io/login">Get started free</a>.</p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/setup-guide-for-ai-agents"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item><item><title><![CDATA[What Is AGENTS.md? How Coding Agents Read Your Docs]]></title><description><![CDATA[AGENTS.md tells AI coding agents how to work on your repo. Learn how it differs from CLAUDE.md and how one line keeps your API docs in sync with code.]]></description><link>https://docstar-blog.hashnode.dev/what-is-agents-md-how-coding-agents-read-your-docs</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/what-is-agents-md-how-coding-agents-read-your-docs</guid><category><![CDATA[#agent]]></category><category><![CDATA[agentic ai development]]></category><category><![CDATA[coding agents]]></category><category><![CDATA[AI]]></category><category><![CDATA[#ai-tools]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Mon, 16 Nov 2026 13:11:42 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/7ee78b7a-c64b-4e6e-b0e0-533a8025186b.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>With DocStar, your coding agent can document your API, keep those docs in step with your code and publish them as a docs site, <code>llms.txt</code>, an MCP server and a CLI. The file that tells the agent to do this on every change is <code>AGENTS.md</code>. This guide explains what <a href="http://AGENTS.md">AGENTS.md</a> (and Claude's <a href="http://CLAUDE.md">CLAUDE.md</a>) is, how agents read it, and the few lines that put your API docs on autopilot in DocStar.</p>
<h2>What is <a href="http://AGENTS.md">AGENTS.md</a>?</h2>
<p><a href="http://AGENTS.md"><strong>AGENTS.md</strong></a> <strong>is a plain Markdown file in your repository that tells AI coding agents how to work on your project: how to build and test it, which conventions to follow, and what to do after a change. Think of it as a README written for agents instead of people. It has no required fields; agents read it before they start work.</strong></p>
<p>The format is described at <a href="https://agents.md/">agents.md</a> as "a simple, open format for guiding coding agents" and, as of November 2026, it is stewarded by the Agentic AI Foundation under the Linux Foundation. Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Windsurf, Zed, Devin and many others list support for it.</p>
<h3><a href="http://AGENTS.md">AGENTS.md</a> vs <a href="http://CLAUDE.md">CLAUDE.md</a></h3>
<p><a href="http://CLAUDE.md">CLAUDE.md</a> does the same job for Claude Code. As of November 2026, <a href="https://code.claude.com/docs/en/memory">Claude Code's docs</a> say it reads <code>CLAUDE.md</code>, not <code>AGENTS.md</code>, and recommend a <code>CLAUDE.md</code> that starts with <code>@AGENTS.md</code> so both tools read the same instructions without duplicating them.</p>
<ul>
<li><strong>Read by:</strong> <a href="http://AGENTS.md">AGENTS.md</a>: Codex, Cursor, Gemini CLI, Copilot agent and many more; <a href="http://CLAUDE.md">CLAUDE.md</a>: Claude Code</li>
<li><strong>Location:</strong> <a href="http://AGENTS.md">AGENTS.md</a>: Repo root, plus optional nested files; <a href="http://CLAUDE.md">CLAUDE.md</a>: <code>./CLAUDE.md</code> or <code>./.claude/CLAUDE.md</code></li>
<li><strong>Format:</strong> <a href="http://AGENTS.md">AGENTS.md</a>: Plain Markdown, any headings; <a href="http://CLAUDE.md">CLAUDE.md</a>: Plain Markdown, can import other files</li>
<li><strong>Best practice:</strong> <a href="http://AGENTS.md">AGENTS.md</a>: Your single source of agent rules; <a href="http://CLAUDE.md">CLAUDE.md</a>: One line: <code>@AGENTS.md</code>, then Claude-only extras</li>
</ul>
<h2>How agents read your instructions</h2>
<p>An instruction file works in three simple steps:</p>
<ol>
<li><strong>The agent loads it at the start of a task.</strong> Before it touches code, the agent reads the file at the repo root.</li>
<li><strong>The closest file wins.</strong> In a monorepo you can add an <code>AGENTS.md</code> inside a package. Per <a href="http://agents.md">agents.md</a>, agents read the nearest file in the directory tree, and your chat prompt overrides everything.</li>
<li><strong>It follows the rules on every change.</strong> "Run the tests before committing", "use pnpm", "update the API docs in the same change": whatever you write becomes part of each task.</li>
</ol>
<p>That last point is why <a href="http://AGENTS.md">AGENTS.md</a> matters for documentation. A rule in the file turns "remember to update the docs" from a hope into a standing step of every change the agent makes.</p>
<h2>Why <a href="http://AGENTS.md">AGENTS.md</a> matters for your API docs</h2>
<p>API docs go stale. A developer renames a field or adds a parameter, and the docs get updated later, by someone else, or never.</p>
<p>In DocStar, stale docs cost more than a confused reader. The same published docs feed four things: your docs site, your <code>llms.txt</code>, the <a href="https://docstar.io/blog/what-is-an-mcp-server">MCP server</a> AI agents use to call your API, and the DocStar CLI. If the docs say <code>customer_id</code> and the code now expects <code>customerId</code>, an agent calls your API with the wrong field and the call fails.</p>
<p><a href="http://AGENTS.md">AGENTS.md</a> is how you make the coding agent fix the docs while it is still holding the change. DocStar gives you two ways to do it.</p>
<h2>How <a href="http://AGENTS.md">AGENTS.md</a> works in DocStar</h2>
<h3>Option 1: GitHub Sync, with docs in the same pull request</h3>
<p>With <a href="https://docstar.io/help/integrations/github-sync">DocStar GitHub Sync</a>, your API docs live in the repo next to the code: OpenAPI files in <code>api-docs/</code> and Markdown pages in <code>docs/</code>. Two small files tell the agent what to do:</p>
<ul>
<li><code>docstar.md</code>, DocStar's format guide, in the repo root. It holds the rules for the <code>docs/</code> and <code>api-docs/</code> folders.</li>
<li><strong>One line in</strong> <code>AGENTS.md</code>, straight from our help docs:</li>
</ul>
<pre><code class="language-markdown">- Whenever any endpoint is added, changed, renamed or removed, read `docstar.md` in this repo and follow it to update `api-docs/` in the same change.
</code></pre>
<p>Now the agent updates the endpoint's OpenAPI file in the same commit as the code. The spec change shows up in the pull request diff, so docs get reviewed like code. On push, the DocStar GitHub Action sends the changed files to your collection, and your docs site, MCP tools and CLI commands update with no manual import or copy-paste.</p>
<h3>Option 2: A standing rule that uses the DocStar MCP</h3>
<p>If your team edits docs in DocStar instead of the repo, add this block to <code>AGENTS.md</code> (or <code>CLAUDE.md</code>) with your real IDs:</p>
<pre><code class="language-markdown">## API docs (DocStar)
Docs: &lt;collection URL&gt; (org &lt;orgId&gt;, collection &lt;collectionId&gt;)
When an API changes, update its endpoint in DocStar with the DocStar MCP (https://mcp.docstar.io/mcp). Save as draft; publish only when asked.
</code></pre>
<p>Every time the agent changes an endpoint, it updates the matching doc in DocStar as a draft, and a person publishes it.</p>
<h2>Let your agent set it all up in one prompt</h2>
<p>You don't need to write any of this by hand. Doing GitHub Sync manually is about six steps: find the collection ID, write the specs, create an API token, add the GitHub secret, download the workflow and add <code>docstar.md</code>. Most people stop partway. With the DocStar MCP connected, it is one prompt.</p>
<h3>Step 1: Connect your coding agent to DocStar</h3>
<p>Add DocStar from your assistant's connector directory if it's listed there. If not, add it to Claude Code, Cursor, Codex or another assistant as a custom remote MCP server:</p>
<pre><code class="language-text">https://mcp.docstar.io/mcp
</code></pre>
<p>The first time the agent needs your workspace, you sign in to DocStar in your browser. There is no API key to copy, and the agent gets the same workspaces and permissions your account has. Full steps: <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect your AI assistant</a>.</p>
<h3>Step 2: Give it one prompt</h3>
<p>Open your API's repository in your coding agent and paste:</p>
<blockquote>
<p>Use the DocStar MCP to set up DocStar GitHub Sync for this repo. Read my latest code for the API, not an old OpenAPI file, and write an OpenAPI file in api-docs/ for every endpoint with a clear description, every parameter, a full JSON body example, and success and error responses. Add <a href="http://docstar.md">docstar.md</a> and the DocStar line to <a href="http://AGENTS.md">AGENTS.md</a>, and make <a href="http://CLAUDE.md">CLAUDE.md</a> import <a href="http://AGENTS.md">AGENTS.md</a>. Store the API token as a GitHub secret without showing it in chat. Show me your plan before you change anything.</p>
</blockquote>
<h3>Step 3: What the agent does</h3>
<p>From that one prompt, the agent:</p>
<ul>
<li>Creates (or picks) an API collection in your DocStar workspace.</li>
<li>Reads your routes and writes an OpenAPI file per endpoint in <code>api-docs/</code>, with a stable <code>operationId</code> so later edits update the same endpoint.</li>
<li>Generates a DocStar API token and saves it as the <code>DOCSTAR_API_KEY</code> GitHub secret, without printing it.</li>
<li>Adds the DocStar workflow, <code>docstar.md</code> and the <a href="http://AGENTS.md">AGENTS.md</a> rule.</li>
<li>After the first sync, hands you your collection's MCP URL.</li>
</ul>
<p>It asks before changing anything, and new endpoints arrive as drafts unless they are marked published (<code>x-docstar-published: true</code>).</p>
<h3>Step 4: Review and publish</h3>
<p>Your job is the part only a person should do: check the plan, decide which endpoints stay private, fix naming and tone, and approve the pull request. If you want users to call your API with their own accounts through your MCP server, you enter your OAuth app's details in the collection's MCP tab. Then publish.</p>
<h2>Keep it current</h2>
<p>Once the rule is in <a href="http://AGENTS.md">AGENTS.md</a>, keeping docs current is part of normal coding. Ask for a feature and the agent updates <code>api-docs/</code> in the same change. For a one-off catch-up, prompt it directly:</p>
<blockquote>
<p>I just changed the orders endpoints in this branch. Read <a href="http://docstar.md">docstar.md</a> and update their OpenAPI files in api-docs/ to match the code. Show me the diff.</p>
</blockquote>
<p>Your MCP server keeps up too. DocStar generates a skill, a short quickstart assistants read before using your API, and it follows your docs as they change. Endpoint tools with an empty description follow the endpoint's docs as well. See <a href="https://docstar.io/help/mcp/collection-mcp-server">Build an MCP server for your app</a> and <a href="https://docstar.io/blog/write-mcp-tool-descriptions">How to Write MCP Tool Descriptions That AI Agents Actually Understand</a>.</p>
<p><strong>Be clear on the limits.</strong> The agent still has to do the work. If a developer changes code without an agent, or the agent skips the <code>docstar.md</code> rule, the docs drift and nothing catches it. DocStar does not watch your repo or compare code with docs. Pull request review is your safety net. More on this in <a href="https://docstar.io/blog/keep-api-docs-in-sync-with-code">How to Keep Your API Docs in Sync with Your Code</a>.</p>
<h2>Prefer to write it yourself?</h2>
<p>Download <code>docstar.md</code> into the repo root, add the <a href="http://AGENTS.md">AGENTS.md</a> line above, generate the workflow file for your collection ID, create an API token in DocStar and save it as the <code>DOCSTAR_API_KEY</code> repository secret, then commit and push. Every push that changes <code>docs/</code> or <code>api-docs/</code> syncs from then on. The <a href="https://docstar.io/help/integrations/github-sync">GitHub Sync guide</a> has the exact commands.</p>
<h2>What to put in your <a href="http://AGENTS.md">AGENTS.md</a></h2>
<p>A good file is short and specific. For an API product, cover:</p>
<ul>
<li><strong>Build and test commands</strong>, exactly as you run them.</li>
<li><strong>Code conventions</strong> the agent can't infer.</li>
<li><strong>The docs rule</strong>: the DocStar line, so docs change with the code.</li>
<li><strong>What needs a human</strong>: publishing, secrets, anything destructive.</li>
</ul>
<p>Keep long API guidance out of <a href="http://AGENTS.md">AGENTS.md</a>. Put it in your DocStar MCP server's skill and instructions, where every assistant that uses your API (not just your own coding agent) will read it.</p>
<h2>Why teams choose DocStar</h2>
<ul>
<li><strong>One source, four outputs.</strong> Publish once and get a docs site, <code>llms.txt</code> with Markdown copies of every page, an MCP server and a CLI.</li>
<li><strong>Agent-first setup.</strong> One prompt sets up GitHub Sync, writes the specs and wires the secret.</li>
<li><strong>Docs reviewed like code.</strong> Spec changes land in the same pull request as the code.</li>
<li><strong>Safe by design.</strong> The agent asks first, changes start as drafts, and your permissions apply.</li>
<li><strong>Control over how agents use your API.</strong> Up to 20 endpoint tools, a skill, instructions and per-user sign-in.</li>
</ul>
<h2>FAQ</h2>
<h3>What is <a href="http://AGENTS.md">AGENTS.md</a> used for?</h3>
<p><a href="http://AGENTS.md">AGENTS.md</a> gives AI coding agents project instructions: how to build, test and follow your conventions. With DocStar, it also tells the agent to update your API docs in the same change as the code.</p>
<h3>Should I use <a href="http://AGENTS.md">AGENTS.md</a> or <a href="http://CLAUDE.md">CLAUDE.md</a>?</h3>
<p>Use <a href="http://AGENTS.md">AGENTS.md</a> as the single source, and add a <a href="http://CLAUDE.md">CLAUDE.md</a> that imports it with <code>@AGENTS.md</code> so Claude Code reads the same rules. DocStar's rule works in either file.</p>
<h3>Does DocStar update my docs automatically when code changes?</h3>
<p>DocStar publishes automatically when docs change: on push, GitHub Sync sends changed files from <code>api-docs/</code> and <code>docs/</code> to your collection. Updating the docs is the coding agent's job, driven by the <a href="http://AGENTS.md">AGENTS.md</a> rule. DocStar doesn't watch your repo for code changes.</p>
<h3>Do I need an API key to connect my agent to DocStar?</h3>
<p>No. Add <code>https://mcp.docstar.io/mcp</code>, sign in to DocStar in your browser once, and the agent works with your permissions. GitHub Sync itself uses an API token, which the agent stores as a GitHub secret.</p>
<h3>Will draft docs reach my MCP server?</h3>
<p>No. Only published content reaches your MCP server, so agents calling your API see only what you've approved.</p>
<h2>Get started free</h2>
<p>Add one line to <a href="http://AGENTS.md">AGENTS.md</a> and your API docs change in the same pull request as your code, so the agents calling your API never use an outdated contract. Your AI sets it up in one prompt. <a href="https://app.docstar.io/login">Get started free</a>.</p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/what-is-agents-md"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item><item><title><![CDATA[How to Add AI Docs Search to Your App with DocStar]]></title><description><![CDATA[Add AI docs search to your app with the DocStar Search SDK. Your coding agent wires up Cmd+K search and Ask AI through the DocStar MCP in one prompt.]]></description><link>https://docstar-blog.hashnode.dev/how-to-add-ai-docs-search-to-your-app-with-docstar</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/how-to-add-ai-docs-search-to-your-app-with-docstar</guid><category><![CDATA[ai search]]></category><category><![CDATA[mcp]]></category><category><![CDATA[#ai-tools]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Mon, 16 Nov 2026 13:08:53 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/751814a9-f3d3-45dd-ae3e-54668cb915e8.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>With DocStar you can add AI-powered docs search to your own app in one prompt. The DocStar Search SDK puts a Cmd/Ctrl + K search window and an <strong>Ask AI</strong> chat inside your website or web app, answering from your published DocStar docs. Your coding agent adds it to your code through the DocStar MCP, and you review the change before it ships.</p>
<p>Most users never open your help center. They get stuck inside your product, look for help there, and when they can't find it they open a ticket or give up. In-app docs search fixes that: the answer comes to where the question started. This guide shows how to set it up the DocStar way, with your AI agent doing the work.</p>
<h2>What the DocStar Search SDK gives your users</h2>
<p>The <a href="https://docstar.io/help/integrations/search-sdk">DocStar Search SDK</a> is a small script that searches a published DocStar collection directly. There's no backend to build, no search index to host and no embeddings pipeline to run.</p>
<ul>
<li><strong>Search from anywhere:</strong> How it works in DocStar: Cmd/Ctrl + K opens a search window with live results from your published collection</li>
<li><strong>Answers, not just links:</strong> How it works in DocStar: An <strong>Ask AI</strong> button opens a chat that answers from your docs, with follow-up questions in the same chat</li>
<li><strong>Stay in the flow:</strong> How it works in DocStar: Results open in a side panel (<code>iframe</code>), a new tab or the current tab</li>
<li><strong>Keyboard-first:</strong> How it works in DocStar: Arrow keys to move, Enter to open, Escape to close</li>
<li><strong>Works on any stack:</strong> How it works in DocStar: Plain HTML, React, Vue, Angular and any other web framework, with a mobile-friendly layout</li>
</ul>
<p>Only published pages appear in results, so drafts and work in progress never show up in your app.</p>
<p>It's the same experience readers already get on a published DocStar site, where the search bar says "Ask AI or search docs..." and every page offers <strong>Ask AI about this page</strong>. The SDK brings it into your product.</p>
<h2>Why let your AI agent set it up</h2>
<p>Adding a script tag sounds like a two-minute job. In practice someone has to find the right collection ID, decide where the scripts load, wire a visible Help button, pick how results open, and check that the docs the search will surface are actually good enough to be found. That last part is where in-app search usually goes wrong: a great search box over thin docs just returns nothing faster.</p>
<p>With DocStar, your coding agent handles all of it in one pass, because it can see both sides at once: your app's code in the repo, and your docs in DocStar through the DocStar MCP.</p>
<h2>Step 1: Connect your coding agent to DocStar</h2>
<p>Connect Claude Code, Cursor, Codex or another MCP-capable assistant to DocStar. Use DocStar from your assistant's connector directory if it's listed there, or add it as a custom (remote) MCP server with this URL:</p>
<pre><code class="language-text">https://mcp.docstar.io/mcp
</code></pre>
<p>The first time the agent needs your workspace, you sign in to DocStar in your browser. There's no API key to copy, and the agent works only with the collections your account can access, with your permissions. Full steps: <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect your AI assistant</a>.</p>
<h2>Step 2: Give it one prompt</h2>
<p>Open your app's repo in the agent and paste a prompt like this:</p>
<blockquote>
<p>Use the DocStar MCP to add DocStar docs search to this app. Find our public help docs collection in DocStar and get its collection ID. Read <a href="https://docstar.io/help/integrations/search-sdk">https://docstar.io/help/integrations/search-sdk</a> and add the Search SDK to our main layout so it loads once on every page. Use openMode "iframe" so users stay in the app. Add a visible "Help" button in the header that calls window.DocStarSearch.open(). Then read our app's main screens and list the user questions our published docs don't answer yet, and draft the missing pages as drafts in DocStar. Show me the code diff and the list of draft pages before you save anything.</p>
</blockquote>
<h2>What the agent does</h2>
<p>Here's what happens after you hit Enter:</p>
<ol>
<li><strong>Finds your docs.</strong> Through the DocStar MCP it lists your collections, picks the help docs one with you, and reads the collection ID.</li>
<li><strong>Reads the setup guide.</strong> It reads the Search SDK help page so it uses the real script and options, not a guess.</li>
<li><strong>Adds the SDK to your code.</strong> It loads the script once in your main HTML file or layout, then calls <code>window.DocStarSearch.configure()</code> with your collection ID and options.</li>
<li><strong>Adds a Help button.</strong> Not everyone knows Cmd/Ctrl + K, so it wires a visible button to <code>window.DocStarSearch.open()</code>.</li>
<li><strong>Finds the gaps.</strong> It compares the screens and flows in your code with what your published docs cover, and lists the questions users will search for but won't find.</li>
<li><strong>Drafts the missing pages.</strong> It writes them in your DocStar collection as drafts. Nothing reaches your live docs, or your in-app search, until you publish.</li>
<li><strong>Asks before changing anything.</strong> You see the code diff and the draft list first.</li>
</ol>
<p>The configuration it adds looks like this (from the Search SDK help page):</p>
<pre><code class="language-html">&lt;script src="https://script.docstar.io/scripts/search-sdk/search-sdk.script.min.js"&gt;&lt;/script&gt;
&lt;script&gt;
  window.DocStarSearch.configure({
    collectionId: "your-collection-id",
    openMode: "iframe",
    debounceDelay: 300,
    enableKeyboardShortcut: true,
    minSearchLength: 2
  });
&lt;/script&gt;
</code></pre>
<p>In a React app, the Help button is just:</p>
<pre><code class="language-jsx">function HelpButton() {
  return (
    &lt;button onClick={() =&gt; window.DocStarSearch &amp;&amp; window.DocStarSearch.open()}&gt;
      Help
    &lt;/button&gt;
  );
}
</code></pre>
<h2>Step 3: You review and publish</h2>
<p>Your role is review and the judgment calls the agent shouldn't make alone:</p>
<ul>
<li><strong>Which collection users search.</strong> Point the SDK at your public help docs, not an internal wiki.</li>
<li><strong>How results open.</strong> <code>iframe</code> keeps users in your app while they read. <code>newTab</code> makes sense when your docs should open on their own site, such as your help center on your own domain.</li>
<li><strong>Tone and accuracy of the new pages.</strong> Read each draft, fix anything only your team knows, and publish the ones you're happy with.</li>
<li><strong>Merging the code change.</strong> Review the diff like any other pull request.</li>
</ul>
<p>Once you publish, those pages show up in the search window and in Ask AI answers inside your app.</p>
<h2>Tune it for your users</h2>
<p>The SDK has a short list of options. Ask the agent to change them, or edit them yourself:</p>
<ul>
<li><code>collectionId</code><strong>:</strong> Default: (required); When to change it: Point at the collection your users should search</li>
<li><code>openMode</code><strong>:</strong> Default: (required); When to change it: <code>"iframe"</code> (side panel), <code>"newTab"</code> or <code>"currentTab"</code></li>
<li><code>debounceDelay</code><strong>:</strong> Default: <code>300</code>; When to change it: Raise it if users type long queries, so fewer searches run while they type</li>
<li><code>enableKeyboardShortcut</code><strong>:</strong> Default: <code>true</code>; When to change it: Turn off Cmd/Ctrl + K if your app already uses that shortcut</li>
<li><code>minSearchLength</code><strong>:</strong> Default: <code>2</code>; When to change it: Characters needed before a search runs</li>
</ul>
<p>You can also open and close the window from your own code with <code>window.DocStarSearch.open()</code> and <code>window.DocStarSearch.close()</code>. That's useful for a "Need help?" link next to a tricky form, or an empty state that opens search for the user.</p>
<h2>Keep it current</h2>
<p>In-app search is only as good as the docs behind it. The good news: the SDK searches your published DocStar collection directly, so there's nothing to re-index or redeploy. When you publish an updated page, that's what your users find.</p>
<p>The ongoing job is keeping the docs themselves current, and that's where your agent helps again. When you ship a feature, ask it in the same session:</p>
<blockquote>
<p>Read the changes in this branch. Update the DocStar help pages that describe these screens, and draft new pages for anything new. Save everything as drafts and show me what changed.</p>
</blockquote>
<p>The agent reads the code change, updates the matching pages as drafts, and you publish. To make this a habit, add a line to your repo's <a href="http://AGENTS.md">AGENTS.md</a> or <a href="http://CLAUDE.md">CLAUDE.md</a> telling the coding agent to update the DocStar help docs whenever a user-facing screen changes. That only works when changes go through the agent, so keep a quick docs check in your release review too.</p>
<p>Two more ways to close the loop:</p>
<ul>
<li><strong>Turn repeat questions into FAQs.</strong> DocStar can draft FAQ suggestions from your docs that you approve before they go live. See <a href="https://docstar.io/blog/reduce-support-tickets-with-faqs">How to Reduce Support Tickets with DocStar FAQs and AI</a>.</li>
<li><strong>Read what readers tell you.</strong> DocStar collects thumbs up/down ratings and reader comments on published pages. Use them to decide which pages to fix next. See <a href="https://docstar.io/blog/documentation-analytics">Documentation Analytics: How to Improve Your Docs with DocStar</a>.</li>
</ul>
<h2>Prefer to do it yourself?</h2>
<p>You can skip the agent entirely. Copy your collection ID from the collection's URL in DocStar (it's the part after <code>/collection/</code>), paste the two script tags from the <a href="https://docstar.io/help/integrations/search-sdk">Search SDK guide</a> before the closing <code>&lt;/body&gt;</code> tag, and add a button that calls <code>window.DocStarSearch.open()</code>. Publish the pages you want users to find, and you're done.</p>
<h2>Why teams choose DocStar for in-app help</h2>
<ul>
<li><strong>No search backend.</strong> Two script tags and a collection ID. DocStar hosts the search and the Ask AI chat.</li>
<li><strong>One source for every channel.</strong> The same published docs power your docs site, the in-app search, your <a href="https://docstar.io/blog/launch-help-center-own-domain">help center on your own domain</a>, <code>llms.txt</code> and Markdown copies for AI, and an MCP server for AI assistants.</li>
<li><strong>Agent-first setup and upkeep.</strong> Your coding agent wires the SDK, finds gaps in your docs and drafts fixes through the DocStar MCP. You stay in control of what gets published.</li>
<li><strong>Safe by design.</strong> The agent asks before it changes anything, every edit starts as a draft, and only published pages ever appear in search.</li>
<li><strong>Works with your stack.</strong> Plain HTML, React, Vue, Angular or anything else that renders a web page.</li>
</ul>
<h2>FAQ</h2>
<h3>Do I need a backend or a search service to use the DocStar Search SDK?</h3>
<p>No. The SDK searches your published DocStar collection directly. You add two script tags and your collection ID, and DocStar handles search and Ask AI.</p>
<h3>Will draft or unpublished pages show up in my app?</h3>
<p>No. Only published pages appear in results. Your agent saves its new pages as drafts, and they reach your in-app search only after you publish them.</p>
<h3>Which frameworks does it work with?</h3>
<p>Any web framework, including plain HTML, React, Vue and Angular. Load the scripts once, for example in your main HTML file or layout, and call <code>window.DocStarSearch.open()</code> from any button.</p>
<h3>Can users ask follow-up questions?</h3>
<p>Yes. After results appear, users click <strong>Ask AI</strong>, ask in plain language, and keep asking follow-ups in the same chat. Answers come from your docs.</p>
<h3>Does my coding agent need an API key to work with DocStar?</h3>
<p>No. Add the DocStar MCP (<code>https://mcp.docstar.io/mcp</code>) to your assistant and sign in to DocStar in your browser the first time. The agent uses your permissions and asks before it changes anything.</p>
<h2>Get started free</h2>
<p>Bring your docs to where your users get stuck. Create a DocStar workspace, publish your help docs, connect your coding agent to the DocStar MCP, and ask it to add search to your app.</p>
<p><a href="https://app.docstar.io/login"><strong>Get started free</strong></a></p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/add-ai-docs-search-to-your-app"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item><item><title><![CDATA[MCP vs Function Calling vs Plugins: What's the Difference (and Where DocStar Fits)]]></title><description><![CDATA[MCP vs function calling vs plugins: how each lets AI use your tools, and how DocStar turns your API docs into one MCP server for every assistants.]]></description><link>https://docstar-blog.hashnode.dev/mcp-vs-function-calling-vs-plugins-what-s-the-difference-and-where-docstar-fits</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/mcp-vs-function-calling-vs-plugins-what-s-the-difference-and-where-docstar-fits</guid><category><![CDATA[mcp]]></category><category><![CDATA[mcp server]]></category><category><![CDATA[cli]]></category><category><![CDATA[plugins]]></category><category><![CDATA[functions]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Mon, 16 Nov 2026 13:05:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/edc13b5b-af4b-42f3-91e5-5f2e91922fc6.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>MCP, function calling and plugins all let an AI model use outside tools, but they work at different layers. Function calling is a model feature: your code tells one model which functions exist and runs them itself. Plugins are add-ons built for one specific assistant. MCP (Model Context Protocol) is an open standard: you publish one server, and any MCP-ready assistant can connect to it. With DocStar, your API docs become that MCP server, so one URL works in Claude, ChatGPT, Cursor, VS Code and other MCP-ready assistants.</p>
<p>This guide explains each approach in plain English, shows how they fit together, and then walks through how we at DocStar turn your documented API into an MCP server your users can add in one step, with your own coding agent doing most of the setup.</p>
<h3>The short answer</h3>
<ul>
<li><strong>What it is:</strong> Function calling: A feature of a model's API; Assistant plugins: An add-on for one assistant; MCP: An open protocol between assistants and tools</li>
<li><strong>Who wires it up:</strong> Function calling: You, in your own app's code; Assistant plugins: You, in that assistant's format; MCP: You publish a server once; each assistant connects</li>
<li><strong>Where your tool runs:</strong> Function calling: Inside your app; Assistant plugins: Wherever that assistant expects; MCP: On your MCP server</li>
<li><strong>Works in other assistants?:</strong> Function calling: No, you rebuild it per app; Assistant plugins: No, it's tied to one assistant; MCP: Yes, any MCP-ready client</li>
<li><strong>Best for:</strong> Function calling: Your own AI feature inside your product; Assistant plugins: Reaching users of one specific assistant; MCP: Letting every user's assistant use your product</li>
</ul>
<p>They are not rivals. MCP doesn't replace the model's ability to choose and call tools; it standardises <strong>where those tools come from</strong>, so you don't have to rebuild them for every assistant.</p>
<h3>How each one works</h3>
<h4>Function calling (tool calling)</h4>
<p>Function calling is how a model asks your code to do something. As OpenAI describes it in its docs (as of November 2026), tool calling is a multi-step conversation between your application and the model: you define functions with a JSON schema, the model replies with which function to call and its arguments, your application runs the code, and you send the result back.</p>
<p>That works well when <strong>you</strong> own the app and the model call. The catch: the function definitions live in your code. If a customer wants to use your product from their own Claude or Cursor, your functions aren't there.</p>
<h4>Assistant plugins and extensions</h4>
<p>Plugins and extensions package tools for a single assistant, in that assistant's own format. They can reach that assistant's users, but each new assistant means another build, another review and another thing to maintain.</p>
<h4>MCP (Model Context Protocol)</h4>
<p>The official MCP site defines it (as of November 2026) as "an open-source standard for connecting AI applications to external systems" and compares it to a USB-C port for AI apps. You run one MCP server that lists your tools; any MCP-ready assistant connects, discovers those tools and calls them. Write once, work everywhere.</p>
<p>For the full picture, read our guide <a href="https://docstar.io/blog/what-is-an-mcp-server">What Is an MCP Server?</a>, and for how MCP relates to the API underneath, see <a href="https://docstar.io/blog/mcp-vs-api">MCP vs API</a>.</p>
<h3>Why the hard part is the tool definitions</h3>
<p>Whichever approach you choose, the model only uses your API well if every tool has a clear name, a description of when to use it, every parameter explained and a real example body. That is documentation work. Teams that hand-write function schemas for one app, a plugin manifest for another and an MCP server for a third end up maintaining the same API description three times.</p>
<p>DocStar takes a different route: <strong>your API docs are the source of truth</strong>, and the MCP server is built from them.</p>
<h3>How this works in DocStar</h3>
<p>Every DocStar collection gets its own MCP server. What assistants can do depends on the collection type, according to our <a href="https://docstar.io/help/mcp/collection-mcp-server">Build an MCP Server for Your App</a> guide:</p>
<ul>
<li><strong>Docs and blogs:</strong> What AI assistants can do: Search and read your published pages</li>
<li><strong>API docs:</strong> What AI assistants can do: Search and read your docs, read your API reference, and call your API</li>
</ul>
<p>Only published content is visible. Drafts never reach your MCP server.</p>
<h4>Step 1: Connect your coding agent to DocStar</h4>
<p>Add DocStar to Claude Code, Cursor, Codex or another assistant. Use DocStar from your assistant's connector directory if it's listed there; if not, add it as a custom remote MCP server with this URL:</p>
<pre><code class="language-text">https://mcp.docstar.io/mcp
</code></pre>
<p>The first time the assistant needs your workspace, you sign in to DocStar in your browser. There's no API key to copy, and the assistant works with the same workspaces and permissions you have. Full steps: <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect Your AI Assistant</a>.</p>
<h4>Step 2: Give it one prompt</h4>
<p>Open your API's repository in your coding agent and paste:</p>
<blockquote>
<p>Use the DocStar MCP to turn my app's API into an MCP server. First read <a href="https://docstar.io/mcp/quickstart.md">https://docstar.io/mcp/quickstart.md</a> and follow it step by step. Read my latest code for the API, not an old OpenAPI file, and document each endpoint with a clear description and a full JSON body example.</p>
</blockquote>
<h4>Step 3: Let the agent do the work</h4>
<p>From that one prompt, the agent:</p>
<ul>
<li><strong>Reads your code</strong> and documents each endpoint in a DocStar API collection: purpose, parameters, a full JSON body example and responses.</li>
<li><strong>Gets your MCP URL.</strong> It looks like <code>https://mcp.docstar.io/connector/your_collection_slug</code>.</li>
<li><strong>Picks your main tools.</strong> By default, assistants reach your API through a general "call any API" tool that searches your docs, finds the endpoint and calls it. The agent gives up to <strong>20</strong> of your most important endpoints their own named tools, such as <code>create_payment</code>, so assistants pick them more reliably.</li>
<li><strong>Writes the skill</strong>, the short guide assistants read before using your API: what it's for, the usual order of calls, rules and limits.</li>
<li><strong>Adds instructions</strong>, short rules assistants get every time they connect, such as "Ask for the account id before creating an order" (under 2,000 characters).</li>
</ul>
<p>It asks you before it changes or publishes anything, and its edits are saved as drafts, so nothing reaches your live docs until you say so.</p>
<h4>Step 4: You review and decide</h4>
<p>Your role is judgement, not typing:</p>
<ul>
<li><strong>What stays private.</strong> Decide which endpoints to publish. Only published endpoints reach the MCP server.</li>
<li><strong>Tool names and descriptions.</strong> Skim the 20 named tools. Leave a description empty to follow the endpoint's docs, so the tool stays current when the docs change.</li>
<li><strong>Safety hints.</strong> Mark tools read-only, destructive, idempotent or open-world, so assistants know when to ask before running them.</li>
<li><strong>Sign-in.</strong> If your API needs a logged-in user, enter your OAuth app's authorization URL, token URL, client ID and secret, and a token validation URL in the <strong>MCP</strong> tab, then add the redirect URIs DocStar shows to your OAuth app. That's the one step only you can do. More in <a href="https://docstar.io/blog/mcp-server-authentication">MCP Server Authentication Explained</a>.</li>
</ul>
<p>Then publish, and share the URL. Your users add it to Claude, ChatGPT, Cursor or VS Code and use your product in plain language. You can even serve it on your own domain, such as <code>mcp.yourcompany.com</code>.</p>
<h3>Keep it current</h3>
<p>An MCP server is only as good as the docs behind it, so make updates part of every code change.</p>
<p><strong>Option A: GitHub Sync.</strong> Keep OpenAPI files in an <code>api-docs/</code> folder and Markdown pages in <code>docs/</code>. On every push that changes them, a GitHub Action sends the changes to DocStar. Add DocStar's <code>docstar.md</code> guide to your repo and this line to your <code>AGENTS.md</code>, so your coding agent updates the API docs in the same change:</p>
<pre><code class="language-markdown">- Whenever any endpoint is added, changed, renamed or removed, read `docstar.md` in this repo and follow it to update `api-docs/` in the same change.
</code></pre>
<p>See <a href="https://docstar.io/help/integrations/github-sync">GitHub Sync</a> for the workflow file and secret.</p>
<p><strong>Option B: ask your agent.</strong> After a change, prompt:</p>
<blockquote>
<p>I just changed the refunds endpoints. Update their docs in our DocStar API collection with the DocStar MCP, keep the tools and skill in line, save as draft and show me what changed.</p>
</blockquote>
<p>Because DocStar's generated skill and empty-description tools follow your docs, updating the docs updates what assistants see once you publish.</p>
<h3>Prefer to click?</h3>
<p>Everything above is also in the app. Open your API collection's settings, go to the <strong>MCP</strong> tab, copy the MCP server URL, pick your endpoint tools, write the skill and instructions, and set up sign-in. Your own app can still use function calling against the same documented API; MCP simply adds every other assistant.</p>
<h3>Why teams choose DocStar</h3>
<ul>
<li><strong>One source of truth.</strong> Your API docs, MCP server, and CLI commands all come from the same published collection.</li>
<li><strong>Agent-first setup.</strong> Your coding agent documents the API and configures the server; you review and publish.</li>
<li><strong>Safe by design.</strong> The agent asks first, edits start as drafts, and drafts never reach the MCP server.</li>
<li><strong>Real sign-in.</strong> Users call your API with their own account through OAuth, not shared keys.</li>
<li><strong>More than an MCP server.</strong> Help docs, FAQs, changelog and blog live in the same workspace, on your domain and brand.</li>
</ul>
<h3>FAQ</h3>
<p><strong>Is MCP a replacement for function calling?</strong> No. Models still choose and call tools; MCP standardises how those tools are published, so one DocStar MCP server works in Claude, ChatGPT, Cursor, VS Code and other MCP-ready assistants.</p>
<p><strong>Do I need to write MCP server code to use DocStar?</strong> No. Document your API in a DocStar collection, publish it, and DocStar gives that collection its own MCP server. Your coding agent can do the documenting for you.</p>
<p><strong>How many tools can a DocStar MCP server have?</strong> You can give up to 20 published endpoints their own named tools. Every other published endpoint stays reachable through the general "call any API" tool.</p>
<p><strong>Can users call my API as themselves?</strong> Yes. For API collections, add your OAuth app's details under <strong>Sign-in for API calls</strong> in the MCP tab. The first time an assistant calls your API, the user signs in with their own account.</p>
<p><strong>Will my draft endpoints show up in assistants?</strong> No. Only published content is visible on your DocStar MCP server.</p>
<h3>Get started free</h3>
<p>Turn your API docs into one MCP server that works in every assistant. Connect your coding agent to DocStar, paste the prompt above and review what it builds.</p>
<p><a href="https://app.docstar.io/login"><strong>Get started free</strong></a></p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/mcp-vs-function-calling"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item><item><title><![CDATA[How to Migrate Your Docs to DocStar with Your AI Agent]]></title><description><![CDATA[Migrate your API specs and Markdown guides to DocStar with Claude Code, Cursor or Codex: one prompt, drafts to review, redirects for old links.]]></description><link>https://docstar-blog.hashnode.dev/how-to-migrate-your-docs-to-docstar-with-your-ai-agent</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/how-to-migrate-your-docs-to-docstar-with-your-ai-agent</guid><category><![CDATA[AI]]></category><category><![CDATA[#ai-tools]]></category><category><![CDATA[AI Tools for Developers]]></category><category><![CDATA[mcp]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Mon, 16 Nov 2026 13:01:58 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/f317d231-17cb-4152-b757-2d0a10a13e5b.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>Moving your documentation to DocStar doesn't have to mean a weekend of copy and paste. With DocStar, you connect your AI coding agent (Claude Code, Cursor, Codex or another assistant) to the DocStar MCP, describe the migration in one prompt, and the agent imports your API specs, brings your written guides over as pages and saves everything as drafts. You review, fix the few things that need a human eye, and publish.</p>
<p>This guide shows the agent-first way to migrate your docs to DocStar, what DocStar can import, how to protect your old links, and how to keep the new docs current once you've moved.</p>
<h3>Why migrate your docs to DocStar</h3>
<p>Most teams don't move docs for fun. They move because the API reference lives in one tool, the help center in another, the changelog in a third, and nobody remembers which login does what. DocStar puts all of that in one workspace:</p>
<ul>
<li><strong>API docs, help docs, FAQs, changelog and blog</strong> in one place, with the same team, roles and branding.</li>
<li><strong>An MCP server for every collection</strong>, so AI assistants can search your published docs and, for API collections, call your API.</li>
<li><strong>AI-ready publishing</strong>: a sitemap, an <code>llms.txt</code> file and Markdown copies of every page.</li>
<li><strong>Your domain and your brand</strong>: custom domains, themes and translation.</li>
</ul>
<p>And because DocStar itself has an MCP server, the migration can be done by the same AI agent you already use for code.</p>
<h3>What DocStar can import</h3>
<p>Before you write a prompt, it helps to know what DocStar accepts. From our <a href="https://docstar.io/help/getting-started/import-content">Import Content</a> guide:</p>
<ul>
<li><strong>OpenAPI 3:</strong> File format: <code>.json</code> or <code>.yaml</code>; What DocStar creates: A new collection with your endpoints</li>
<li><strong>Swagger 2.0:</strong> File format: <code>.json</code> or <code>.yaml</code>; What DocStar creates: A new collection (converted to OpenAPI automatically)</li>
<li><strong>Postman collection:</strong> File format: <code>.json</code>; What DocStar creates: A new collection with your requests and folders</li>
<li><strong>DocStar export:</strong> File format: <code>.json</code>; What DocStar creates: A copy of a collection exported from DocStar</li>
<li><strong>Markdown:</strong> File format: <code>.md</code>, <code>.markdown</code> or <code>.mdx</code>; What DocStar creates: New pages inside an existing collection</li>
</ul>
<p>Other formats, such as XML, aren't supported. Markdown import isn't available for Embed collections. If your written docs live in another docs tool or a wiki, export them as Markdown first; if they already live in a Git repo as Markdown, you're ready.</p>
<h3>Migrate your docs with your AI agent (the recommended way)</h3>
<p>This is the workflow we use and recommend. Your agent does the repetitive work; you make the calls that need judgment.</p>
<h4>Step 1: Connect your agent to DocStar</h4>
<p>Add DocStar to your assistant once. If DocStar is in your assistant's connector directory, connect it from there. If not, add it as a custom (remote) MCP server with this URL:</p>
<pre><code class="language-text">https://mcp.docstar.io/mcp
</code></pre>
<p>The first time the agent needs your workspace, you sign in to DocStar in your browser. There's no API key to copy, and the agent only sees the workspaces and collections your DocStar account can access, with the same permissions you have. Full steps are in <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect Your AI Assistant</a>.</p>
<h4>Step 2: Give it one prompt</h4>
<p>Open your agent in the repo or folder that holds your old docs and paste something like this:</p>
<blockquote>
<p>Use the DocStar MCP to migrate our documentation into DocStar. Import our OpenAPI spec in <code>openapi.yaml</code> as a new API collection. Then create a "Help Docs" collection and bring over every Markdown file in <code>docs/</code> as a page, keeping the same folder structure and page order. Keep each page's old URL slug where you can. Make a list of any old URLs that will change. Save everything as drafts, show me your plan before you change anything, and don't publish.</p>
</blockquote>
<p>Adjust the file names and collection names to match your project. If your API spec is out of date, say so: ask the agent to read your latest code for the API instead and document each endpoint with a clear description and a full JSON body example, the same approach our <a href="https://docstar.io/blog/how-to-document-a-rest-api">How to Document a REST API with DocStar</a> guide describes.</p>
<h4>Step 3: Let the agent do the heavy lifting</h4>
<p>Here's what the agent does through the DocStar MCP:</p>
<ol>
<li><strong>Finds your workspace</strong> and the right collections, or proposes new ones.</li>
<li><strong>Shows you its plan</strong> and asks before it creates or changes anything.</li>
<li><strong>Imports your API spec</strong> as a collection of endpoints.</li>
<li><strong>Creates your guide pages</strong> from your Markdown files, with titles and slugs.</li>
<li><strong>Lists the URLs that changed</strong>, so you can redirect them.</li>
<li><strong>Leaves everything as drafts.</strong> Imported pages and endpoints start as drafts, so nothing reaches readers (or your MCP server) until you publish.</li>
</ol>
<h4>Step 4: Review like an editor, not a typist</h4>
<p>Your job now is review, not retyping. Open the new collections in DocStar and check:</p>
<ul>
<li><strong>Structure and naming.</strong> Does the sidebar read the way a new customer would expect? Rename or reorder anything that feels off.</li>
<li><strong>What stays private.</strong> Old docs often hide internal notes, test endpoints or half-finished pages. Decide what to leave out before you publish.</li>
<li><strong>API details.</strong> Check imported endpoints for base URLs and auth settings, as our import guide recommends.</li>
<li><strong>Tone and leftovers.</strong> Files exported from another tool can carry formatting that only made sense there. Tidy it up, or ask the agent to do it: "Clean up leftover formatting on every page in Help Docs and show me the diff first."</li>
</ul>
<p>Want help with a big batch? Ask the agent for a review checklist of every imported page, then work through it.</p>
<h4>Step 5: Protect your old links with redirects</h4>
<p>Links from search results, blog posts and support replies still point at your old URLs. DocStar handles redirects in two ways, both covered in our <a href="https://docstar.io/help/publish-and-seo/redirects">Redirects</a> guide:</p>
<ul>
<li><strong>Automatic redirects</strong> whenever you change a page's slug or move a page in DocStar.</li>
<li><strong>Manual redirects</strong> in <strong>Settings &gt; Redirections</strong>, made for exactly this case: old paths visitors are still using after a migration from another tool.</li>
</ul>
<p>Redirects only help if readers reach DocStar first, so this matters most when your DocStar docs take over the same domain as your old docs. Hand the agent the list of changed URLs from Step 3:</p>
<blockquote>
<p>For every old URL in this list, add a redirect in the Help Docs collection to the matching new page. Show me the full list before you save.</p>
</blockquote>
<h4>Step 6: Put the docs on your domain and publish</h4>
<p>Connect a custom domain such as <code>docs.yourcompany.com</code> (CNAME) or a path such as <code>yourcompany.com/help</code> (Cloudflare Worker). This matters for SEO: pages on the default DocStar link are marked <code>noindex</code>, so search engines only index your docs on your own domain.</p>
<p>When you're happy, publish. DocStar then serves your docs with a sitemap, an <code>llms.txt</code> file and a Markdown copy of every page, and each collection's MCP server can search and read the published pages. Drafts never reach your MCP server.</p>
<h3>Keep it current after the move</h3>
<p>A migration is only worth it if the new docs don't drift. With DocStar you have two agent-friendly options.</p>
<p><strong>Option 1: GitHub Sync.</strong> Keep Markdown pages in a <code>docs/</code> folder and OpenAPI files in an <code>api-docs/</code> folder in your repo. On every push that changes them, a GitHub Action sends the changes to DocStar, which creates, updates or archives the matching pages and endpoints. New items are created as drafts unless you mark them as published. The repo also holds a <code>docstar.md</code> format guide that your AI coding assistant reads, so the agent writes docs in the right shape whenever it changes code. See <a href="https://docstar.io/help/integrations/github-sync">GitHub Sync</a>.</p>
<p><strong>Option 2: A standing instruction for your agent.</strong> If you'd rather edit in DocStar, add a short rule to your repo's <code>AGENTS.md</code> or <code>CLAUDE.md</code>:</p>
<pre><code class="language-markdown">## API docs (DocStar)
Docs: &lt;collection URL&gt; (org &lt;orgId&gt;, collection &lt;collectionId&gt;)
When an API changes, update its endpoint in DocStar with the DocStar MCP (https://mcp.docstar.io/mcp). Save as draft; publish only when asked.
</code></pre>
<p>Now every time your agent changes an endpoint, it updates the docs too, and you approve the draft.</p>
<h3>Prefer to do it by hand?</h3>
<p>You can run the whole migration in the DocStar app:</p>
<ol>
<li><strong>API spec:</strong> click the collection name at the top of the left sidebar, choose <strong>Import collection</strong>, and drop in your OpenAPI, Swagger or Postman file.</li>
<li><strong>Markdown pages:</strong> open the collection, go to <strong>Settings &gt; Collection Actions</strong>, click <strong>Import</strong> next to <strong>Import Pages</strong>, and select your <code>.md</code> or <code>.mdx</code> files. You can pick several at once; each becomes a page.</li>
<li><strong>Redirects:</strong> in <strong>Settings &gt; Redirections</strong>, type the old slug, pick the destination page and click <strong>Add</strong>.</li>
</ol>
<p>It works well for small sites. For anything bigger, let the agent do the repetitive part.</p>
<h3>Why teams choose DocStar</h3>
<ul>
<li><strong>One home for every kind of doc.</strong> API reference, guides, FAQs, changelog and blog share one workspace, one team and one brand. See how it fits together in <a href="https://docstar.io/blog/build-developer-portal-with-docstar">How to Build a Developer Portal with DocStar</a>.</li>
<li><strong>Agent-first from day one.</strong> Your AI assistant can do your documentation work through the DocStar MCP, and asks before it changes anything.</li>
<li><strong>AI-ready output.</strong> Every collection gets its own MCP server, plus a sitemap, <code>llms.txt</code> and Markdown copies of every page.</li>
<li><strong>Safe by default.</strong> Imports and agent changes land as drafts. Nothing goes live until a person publishes it.</li>
<li><strong>Old links keep working.</strong> Automatic and manual redirects protect your traffic through the move.</li>
</ul>
<h3>FAQ</h3>
<h4>Can my AI agent migrate my docs to DocStar for me?</h4>
<p>Yes. Connect Claude Code, Cursor, Codex or another assistant to the DocStar MCP at <code>https://mcp.docstar.io/mcp</code>, sign in once in your browser, and ask it to import your specs and Markdown pages. It works with your permissions, asks before changing anything, and your imports start as drafts.</p>
<h4>What formats can I import into DocStar?</h4>
<p>OpenAPI 3 and Swagger 2.0 (<code>.json</code> or <code>.yaml</code>), Postman collections, DocStar exports, and Markdown files (<code>.md</code>, <code>.markdown</code>, <code>.mdx</code>). Other formats, such as XML, aren't supported.</p>
<h4>Will my old documentation URLs break?</h4>
<p>Not if you add redirects. In <strong>Settings &gt; Redirections</strong> you can point each old path to its new page, and DocStar adds redirects automatically when you later rename or move a page.</p>
<h4>Will my migrated docs show up in Google?</h4>
<p>They can be indexed once they're published on a custom domain. Pages on the default DocStar link are marked <code>noindex</code>, so connect your own domain to get indexed.</p>
<h4>Does anything go live during the migration?</h4>
<p>No. Imported pages and endpoints normally start as drafts, and drafts never reach your MCP server. You decide when to publish.</p>
<h3>Get started free</h3>
<p>Bring your docs into one DocStar workspace, on your own domain and ready for AI assistants. Connect your agent, paste the prompt above, and review the drafts.</p>
<p><a href="https://app.docstar.io/login"><strong>Get started free</strong></a></p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/migrate-docs-to-docstar"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item><item><title><![CDATA[1. Documentation Analytics: How to Improve Your Docs with DocStar]]></title><description><![CDATA[See which docs pages confuse readers with DocStar analytics and reader feedback, then let your AI agent write fixes as drafts you review and publish.]]></description><link>https://docstar-blog.hashnode.dev/1-documentation-analytics-how-to-improve-your-docs-with-docstar</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/1-documentation-analytics-how-to-improve-your-docs-with-docstar</guid><category><![CDATA[AI]]></category><category><![CDATA[analytics]]></category><category><![CDATA[documentation]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Mon, 16 Nov 2026 13:00:02 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/0d650bbb-6908-4b1c-9b6e-720b1e7eec27.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>DocStar tracks how readers use your published docs: which pages they read, whether each one helped, and where they came from. With DocStar you can hand that data to your AI coding agent, ask it to find the pages that are failing readers, and get fixes back as drafts you review. This guide shows the full workflow, from connecting your agent to a monthly docs check-up that keeps working after the first pass.</p>
<h3>What DocStar measures on every published page</h3>
<p>Every DocStar collection has its own <strong>Analytics</strong> dashboard. There's nothing to install and no script to add. Publish a page and DocStar starts counting.</p>
<ul>
<li><strong>Reads:</strong> What it tells you: How many times each page or API endpoint was viewed</li>
<li><strong>Status:</strong> What it tells you: Whether a page is <strong>Live</strong> or still a <strong>Draft</strong></li>
<li><strong>SEO Score:</strong> What it tells you: An AI SEO score out of 100 for each published page</li>
<li><strong>Positive / Negative:</strong> What it tells you: <strong>Yes</strong> and <strong>No</strong> votes from "Was this helpful?"</li>
<li><strong>Feedback:</strong> What it tells you: Written comments readers leave after voting No</li>
<li><strong>UTM Count:</strong> What it tells you: Visits that arrived through links with tracking parameters</li>
</ul>
<p>The top of the dashboard shows collection totals: Total Reads, Total Pages, Positive Feedback, Negative Feedback, Total UTM Counts and Total Feedback. You can filter by <strong>All Time</strong>, <strong>Last Month</strong>, <strong>Last Week</strong> or a custom range (custom ranges are rounded to full Monday-to-Sunday weeks), and by live or unpublished pages. The full reference is in our <a href="https://docstar.io/help/analytics-and-feedback/analytics">Analytics help page</a>.</p>
<h4>Reader feedback comes built in</h4>
<p>Every published page and API endpoint shows <strong>Was this helpful?</strong> at the bottom. <strong>Yes</strong> counts as positive. <strong>No</strong> opens a short form, "Sorry to hear that. What can we do better?", where the reader writes a comment and can leave an email address. Readers don't need an account, and feedback is on by default. See <a href="https://docstar.io/help/analytics-and-feedback/reader-feedback">Reader Feedback</a> for the details.</p>
<h4>UTM tracking without setup</h4>
<p>When someone opens a published page from a link with query parameters, such as <code>?utm_source=newsletter&amp;utm_campaign=june-launch</code>, DocStar records them. Any parameters count, not only <code>utm_</code> ones, and a repeat visit with the same parameters in the same browser session is counted once. DocStar also tags outbound links: when a reader clicks from your docs to your main domain (for example from <code>docs.example.com</code> to <code>example.com/pricing</code>), it adds <code>utm_source</code> with the docs page URL, so your website analytics show which docs page sent the visitor.</p>
<h3>Why documentation analytics usually go unused</h3>
<p>Most teams have some numbers about their docs. Few act on them. Reading a dashboard, cross-checking comments against the page, and then rewriting the page is slow work that loses to every other priority.</p>
<p>DocStar changes who does the slow part. The same data the dashboard shows is available through the DocStar API, including per-page analytics and a collection's reader feedback with weekly Yes and No counts and the comments. An AI agent connected to DocStar can read all of it, open the pages, and draft the fixes. Your job becomes the part that needs a person: deciding what's right.</p>
<h3>Let your AI agent run the docs review with DocStar</h3>
<p>This is the main workflow we recommend. It takes one connection and one prompt.</p>
<h4>Step 1: Connect your agent to DocStar</h4>
<p>Add DocStar to Claude Code, Cursor, Codex or another assistant. If DocStar is in your assistant's connector directory, connect it from there. Otherwise, add it as a custom remote MCP server with this URL:</p>
<pre><code class="language-text">https://mcp.docstar.io/mcp
</code></pre>
<p>The first time the agent needs your workspace, you sign in to DocStar in your browser. There's no API key to copy. The agent works only with the workspaces and collections your account can access, with your permissions. Full steps are in <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect Your AI Assistant</a>.</p>
<h4>Step 2: Give it one prompt</h4>
<p>Paste something like this, changing the collection name:</p>
<blockquote>
<p>Use the DocStar MCP. In our "Help Docs" collection, pull the last 4 weeks of reader feedback and page analytics. Rank pages by reads and No votes, and read every comment. For the top 5 problem pages, open the page, explain what readers are missing, and draft a fix. Turn questions that keep coming up into pending FAQs. Show me your plan before you change anything, save every edit as a draft, and don't publish.</p>
</blockquote>
<h4>Step 3: What the agent does</h4>
<p>With that prompt, the agent:</p>
<ol>
<li><strong>Finds the collection</strong> in your workspace and lists its pages.</li>
<li><strong>Reads the numbers.</strong> It pulls reader feedback (Yes and No counts by week, plus comments) and page analytics (reads by week, UTM records).</li>
<li><strong>Prioritizes.</strong> It follows the same advice we give people: a popular page with many No votes comes first.</li>
<li><strong>Reads the comments against the page.</strong> Comments often point to a missing step, an outdated screenshot or an unclear term, and the agent can check the current page text to confirm.</li>
<li><strong>Proposes a plan</strong> and waits for your OK. The agent asks before it changes anything.</li>
<li><strong>Drafts the fixes.</strong> Rewrites go in as drafts, and repeated questions become pending FAQs that show up on the right pages once approved.</li>
</ol>
<h4>Step 4: Review and publish</h4>
<p>Every change the agent makes is saved as a draft. Nothing reaches your live docs until it is published, so readers keep seeing the current version while you review. Open the drafts in DocStar's editor, adjust anything you like, and publish, or tell the agent which pages to publish for you.</p>
<h3>What stays with you</h3>
<p>The agent handles the reading, matching and drafting. A few calls belong to a person, and we built DocStar so they stay with you:</p>
<ul>
<li><strong>Judgment on fixes.</strong> A comment may ask for something you don't support. You decide whether the page should explain it, or not promise it at all.</li>
<li><strong>What stays private.</strong> Workarounds, pricing exceptions and internal details shouldn't land in public docs because one reader asked.</li>
<li><strong>Tone and naming.</strong> You keep the voice of your docs consistent.</li>
<li><strong>Replying to readers.</strong> If a reader left an email, follow up and let them know you fixed it. That small step builds a lot of trust.</li>
</ul>
<h3>Go further: SEO scores and traffic sources</h3>
<p>Analytics isn't only about fixing confusing pages. Two more prompts we find useful:</p>
<ul>
<li><strong>Low SEO scores.</strong> Sort by <strong>SEO Score</strong> in the dashboard, then ask the agent to "rewrite the titles and meta descriptions for these pages so they match what people search for, as drafts".</li>
<li><strong>Which channels work.</strong> Add UTM parameters to the links you share in emails, release notes, social posts and in-app help. Then ask the agent to "summarize last month's UTM sources by page and tell me which channels bring readers to our setup guides".</li>
</ul>
<p>If your docs live on a custom domain, the same analytics apply. Our guide on <a href="https://docstar.io/blog/launch-help-center-own-domain">launching a help center on your own domain</a> covers that setup.</p>
<h3>Keep it current</h3>
<p>A single cleanup helps for a month. A habit helps for good. With DocStar, keeping docs healthy is a routine your agent runs, not a project.</p>
<ul>
<li><strong>Monthly check-up.</strong> Re-run the prompt each month with "compare with last month and tell me whether No votes on the pages we fixed went down". This is our "fix and republish, then watch the negative count" advice, done for you.</li>
<li><strong>After each release.</strong> When your code changes, ask the agent: "Read what changed in this release, find the DocStar pages it affects, and update them as drafts." It updates the docs before readers find the gap.</li>
<li><strong>FAQs from feedback.</strong> Repeat questions in comments become pending FAQs you approve, the same loop we describe in <a href="https://docstar.io/blog/reduce-support-tickets-with-faqs">How to Reduce Support Tickets with DocStar FAQs and AI</a>.</li>
</ul>
<h3>Prefer to click?</h3>
<p>You can do the same review by hand. Open a collection and click <strong>Analytics</strong> in the left sidebar. Click the <strong>Negative Feedback</strong> card to show only pages with No votes, sort by <strong>Reads</strong>, and click a page's <strong>Feedback</strong> count to read the comments. You can also click the <strong>viewed</strong> count in any page's header to see its views, UTM sources and feedback while you edit. To hide the feedback widget, turn off <strong>Feedback</strong> under <strong>Settings</strong> &gt; <strong>Theme &amp; Customization</strong>.</p>
<h3>Why teams choose DocStar</h3>
<ul>
<li><strong>Analytics in the same place as the docs.</strong> Reads, feedback, SEO scores and UTM sources sit next to the pages, FAQs and changelog they describe. No separate analytics tool to wire up.</li>
<li><strong>Feedback on every page and endpoint.</strong> Help articles and API reference pages both collect Yes/No votes and comments.</li>
<li><strong>Agent-ready by design.</strong> The DocStar MCP lets Claude Code, Cursor or Codex read your analytics and draft the fixes, with browser sign-in and your own permissions.</li>
<li><strong>Safe by default.</strong> Agent edits are drafts, the agent asks before changing anything, and nothing goes live until it's published.</li>
<li><strong>One workspace for everything.</strong> API docs, help docs, FAQs, changelog and blog, each with its own MCP server for your users' AI assistants.</li>
</ul>
<h3>FAQ</h3>
<p><strong>Do I need to install anything to get analytics in DocStar?</strong> No. Every collection has an Analytics dashboard, and reads, feedback and UTM visits are recorded once pages are published.</p>
<p><strong>Do readers need an account to leave feedback?</strong> No. Anyone can click Yes or No. A No opens a short comment form, and the reader can add an email address if they want a reply.</p>
<p><strong>Can my AI agent publish the fixes itself?</strong> Only if you ask it to. By default every agent edit is saved as a draft, the agent asks before it changes anything, and you decide what to publish.</p>
<p><strong>Does feedback work on API reference pages?</strong> Yes. Feedback is counted per page for both pages and API endpoints.</p>
<p><strong>Can I turn the feedback widget off?</strong> Yes. In the collection's <strong>Settings</strong>, go to <strong>Theme &amp; Customization</strong>, turn off <strong>Feedback</strong> and save.</p>
<h3>Get started free</h3>
<p>Your docs already know which pages are failing readers. With DocStar, your AI agent reads the signals and drafts the fixes, and you make the final call. <a href="https://app.docstar.io/login">Get started free</a> and connect your agent to DocStar in a few minutes.</p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/documentation-analytics"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item><item><title><![CDATA[What Is OpenAPI? A Plain-English Guide]]></title><description><![CDATA[What is OpenAPI? A plain-English guide to the API spec, and how DocStar turns it into API docs, an MCP server and a CLI written by your AI agent.]]></description><link>https://docstar-blog.hashnode.dev/what-is-openapi-a-plain-english-guide</link><guid isPermaLink="true">https://docstar-blog.hashnode.dev/what-is-openapi-a-plain-english-guide</guid><category><![CDATA[AI]]></category><category><![CDATA[OpenApi]]></category><category><![CDATA[documentation]]></category><category><![CDATA[api]]></category><dc:creator><![CDATA[DocStar]]></dc:creator><pubDate>Fri, 13 Nov 2026 12:37:48 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af69d5e3b0c53da1c3330a9/c56f35cb-6598-4193-969f-919bc7b03cf9.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>OpenAPI is the standard, machine-readable way to describe a REST API: every endpoint, parameter, request body, response and auth rule, written in one YAML or JSON file that both people and tools can read. With DocStar, that one file becomes your published API reference, a hosted MCP server for AI assistants and a CLI, and your coding agent can write or update it for you straight from your code.</p>
<p>This guide explains OpenAPI in plain English, then shows how the DocStar team recommends working with it in 2026: let your AI agent do the writing, and keep the human job to review and publish.</p>
<h3>What is OpenAPI, in plain English?</h3>
<p>Think of an OpenAPI file as a contract for your API. Instead of a wiki page that says "send a POST to /orders with a customer id", the file states it in a structured format:</p>
<ul>
<li><strong>Where</strong> the API lives (the server URL)</li>
<li><strong>Which paths and methods</strong> exist (<code>GET /orders</code>, <code>POST /orders</code>)</li>
<li><strong>What goes in</strong> (path and query parameters, headers, the JSON body and its field types)</li>
<li><strong>What comes back</strong> (status codes and response shapes)</li>
<li><strong>How to authenticate</strong> (API key, bearer token, OAuth 2.0)</li>
</ul>
<p>Because the format is standard, any tool that understands OpenAPI can read your file and do something useful with it: render docs, generate code, run tests or, increasingly, give an AI agent the tools to call your API.</p>
<p>The specification is maintained by the OpenAPI Initiative, a Linux Foundation project. As of November 2026 the latest release line is OpenAPI 3.2, which the Initiative announced in September 2025. Most real-world specs you'll meet are OpenAPI 3.0 or 3.1, plus older files in the Swagger 2.0 format.</p>
<h3>How OpenAPI works: a quick example</h3>
<p>Here is a tiny OpenAPI 3 snippet for one endpoint:</p>
<pre><code class="language-yaml">openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /orders:
    post:
      summary: Create an order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customerId, items]
              properties:
                customerId: { type: string }
                items: { type: array, items: { type: string } }
      responses:
        "201":
          description: Order created
</code></pre>
<p>That is the whole idea: one structured description that people can read and machines can act on.</p>
<h4>OpenAPI vs Swagger vs API docs</h4>
<p>These terms get mixed up a lot, so here is the short version:</p>
<ul>
<li><strong>OpenAPI:</strong> What it means: The specification (the format) for describing REST APIs</li>
<li><strong>Swagger 2.0:</strong> What it means: The older name and version of the same format, before it became OpenAPI 3</li>
<li><strong>OpenAPI file / spec:</strong> What it means: Your API described in that format, as <code>.yaml</code> or <code>.json</code></li>
<li><strong>API documentation:</strong> What it means: The human-friendly reference site built from the spec, plus guides and examples</li>
<li><strong>MCP server:</strong> What it means: A way for AI assistants to discover and call your API, which a good spec makes possible</li>
</ul>
<p>An OpenAPI file on its own is not documentation your users will love. It needs a home where it becomes a readable, testable reference, and today it also needs to be usable by AI agents. That is where DocStar comes in.</p>
<h3>Why OpenAPI matters more in the age of AI agents</h3>
<p>AI assistants such as Claude, ChatGPT, Cursor and Codex now call APIs on behalf of users. To do that well, they need exactly what a good OpenAPI file provides: clear endpoint descriptions, typed parameters and full body examples. A vague spec leads to wrong tool calls; a precise one leads to agents that get it right the first time.</p>
<p>That's why, in DocStar, your API documentation does three jobs from one source:</p>
<ol>
<li><strong>A published API reference</strong> for developers, with a <strong>TRY</strong> button to send live requests and ready-made code snippets in languages such as Shell (cURL), Node, Python, Java, Go and PHP.</li>
<li><strong>A hosted MCP server</strong> for the collection, so AI assistants can search your docs, read your API reference and call your API.</li>
<li><strong>The DocStar CLI</strong>, which turns published API endpoints into terminal commands (and MCP tools) and reads the docs each time a command runs, so there is nothing to regenerate.</li>
</ol>
<p>You describe your API once, and DocStar serves humans, agents and the terminal.</p>
<h3>How OpenAPI works in DocStar: let your AI agent do it</h3>
<p>DocStar is built agent-first. You don't need to hand-write YAML or click through forms. Connect your coding agent to DocStar and ask for what you want in plain language.</p>
<h4>Step 1: Connect your agent to the DocStar MCP</h4>
<p>Add the DocStar MCP URL, <code>https://mcp.docstar.io/mcp</code>, to Claude Code, Cursor, Codex or another MCP-capable assistant (or add DocStar from your assistant's connector directory). The first time the agent needs your workspace, you sign in to DocStar in your browser. There is no API key to copy, and the agent gets the same permissions your account has. Full steps are in <a href="https://docstar.io/help/mcp/connect-ai-assistant">Connect your AI assistant</a>.</p>
<h4>Step 2: Give it one prompt</h4>
<p>Whether you already have an OpenAPI file or only have code, one prompt is enough. Here is one you can paste as-is:</p>
<blockquote>
<p>Use the DocStar MCP to document my API in DocStar. First read <a href="https://docstar.io/mcp/quickstart.md">https://docstar.io/mcp/quickstart.md</a> and follow it step by step. Read my latest code for the API, not an old OpenAPI file, and document each endpoint with a clear description, every parameter, a full JSON request body example, and success and error responses. Show me your plan before you change anything and save everything as drafts.</p>
</blockquote>
<h4>Step 3: What the agent does</h4>
<p>From that prompt, the agent:</p>
<ul>
<li><strong>Reads your routes and handlers</strong> to find every endpoint, rather than trusting a spec that may be out of date.</li>
<li><strong>Documents each endpoint</strong> in a DocStar API collection: method, full URL, headers, parameters, request body and sample responses.</li>
<li><strong>Shows you what it will create or change</strong> and waits for your OK. Every change is saved as a draft, so nothing reaches your live docs until it is published.</li>
<li><strong>Sets up your MCP server</strong> if you ask: it picks up to 20 of your most important endpoints as tools of their own, writes the skill assistants read before using your API, and adds instructions they follow every time they connect.</li>
</ul>
<h4>Step 4: You review and publish</h4>
<p>Your role is the part that needs judgment: which endpoints stay private, how things are named, the tone of descriptions, and anything only a person can enter, such as your OAuth app details for MCP sign-in. When the drafts look right, publish them yourself or tell the agent to publish. Only published content appears in your reference, your MCP server and the CLI.</p>
<p>If you'd like the full walkthrough of the MCP side, see <a href="https://docstar.io/blog/openapi-to-mcp-server">OpenAPI to MCP Server: Let Your AI Agent Set It Up with DocStar</a>.</p>
<h3>Keep your OpenAPI docs current</h3>
<p>A spec is only useful while it matches the code. DocStar gives you two agent-friendly ways to keep it that way.</p>
<p><strong>Option 1: GitHub Sync with OpenAPI files.</strong> Keep your OpenAPI files in an <code>api-docs/</code> folder in your repository. DocStar's GitHub Action syncs every push that changes them, creating, updating or archiving the matching endpoints in your collection. Add DocStar's <code>docstar.md</code> format guide to the repo and a line to your <code>AGENTS.md</code>, and your coding agent updates <code>api-docs/</code> in the same change whenever an endpoint is added, changed, renamed or removed. Set <code>x-docstar-published: true</code> on each operation so your endpoints are published. Setup is in <a href="https://docstar.io/help/integrations/github-sync">GitHub Sync</a>.</p>
<p><strong>Option 2: Ask the agent after each change.</strong> If you don't use GitHub Sync, add a short note to your <code>AGENTS.md</code> or <code>CLAUDE.md</code> telling the agent to update the endpoint in DocStar through the DocStar MCP whenever an API changes, saving as a draft. A ready-to-use prompt for that moment:</p>
<blockquote>
<p>I just changed the orders endpoints in this branch. Use the DocStar MCP to update their docs in our API collection to match the code, and show me the changes before you save. Keep them as drafts.</p>
</blockquote>
<p>Either way, you review the diff and publish. The docs, the MCP tools and the CLI commands all follow.</p>
<h3>Prefer to do it yourself?</h3>
<p>You can also bring an existing spec in by hand. In DocStar, use <strong>Import collection</strong> and drop in an OpenAPI 3.x or Swagger 2.0 file (JSON or YAML) or a Postman collection; each import creates a new API collection, and Swagger 2.0 files are converted to OpenAPI automatically. Check base URLs and auth settings before you publish. Going the other way, <strong>Export Collection</strong> can produce an OpenAPI file, though an OpenAPI export drops versions and endpoint descriptions. Details are in <a href="https://docstar.io/help/getting-started/import-content">Import Content</a>.</p>
<h3>Why teams choose DocStar for OpenAPI-based docs</h3>
<ul>
<li><strong>One source, three outputs.</strong> The same published endpoints power your API reference, your hosted MCP server and the DocStar CLI.</li>
<li><strong>Agent-first by design.</strong> Your coding agent reads the code, writes the docs, asks before changing anything and saves drafts. You review and publish.</li>
<li><strong>Docs-as-code when you want it.</strong> GitHub Sync turns your <code>api-docs/</code> OpenAPI files into published endpoints on every push.</li>
<li><strong>Interactive for developers.</strong> Readers can send live requests with <strong>TRY</strong> and copy code snippets.</li>
<li><strong>Everything in one workspace.</strong> API docs sit next to your help docs, FAQs, changelog and blog, on your own domain and brand.</li>
</ul>
<h3>FAQ</h3>
<h4>Do I need an OpenAPI file to use DocStar?</h4>
<p>No. If you have one, DocStar can import it. If you don't, your AI agent can read your code and document each endpoint directly in DocStar through the DocStar MCP. Many teams prefer this, because the agent works from the latest code rather than an old spec.</p>
<h4>Which OpenAPI versions does DocStar import?</h4>
<p>DocStar imports OpenAPI 3.x and Swagger 2.0 files in JSON or YAML, as well as Postman collections and DocStar exports. Swagger 2.0 files are converted to OpenAPI automatically.</p>
<h4>Is OpenAPI the same as an MCP server?</h4>
<p>No. OpenAPI describes your API; an MCP server lets AI assistants discover and call it. In DocStar, every API collection can run its own MCP server built from your documented endpoints, so a well-described API gets you both.</p>
<h4>Will the agent publish changes without asking?</h4>
<p>No. The agent shows you what it will create, change or publish and waits for your OK, and every edit is saved as a draft first. Nothing reaches your live docs until it is published.</p>
<h4>Can I generate a CLI from my OpenAPI spec?</h4>
<p>Yes. Once your endpoints are published in DocStar, the DocStar CLI turns them into commands with nothing to generate or keep in sync. See <a href="https://docstar.io/blog/generate-cli-from-openapi">How to Generate a CLI from Your OpenAPI Spec</a>.</p>
<h3>Get started free</h3>
<p>OpenAPI tells the world what your API does. DocStar turns it into docs developers enjoy, an MCP server AI assistants can use and a CLI, with your coding agent doing the writing. <a href="https://app.docstar.io/login">Get started free</a> and give your agent its first prompt today.</p>
<hr />
<p><em>Originally published on the</em> <a href="https://docstar.io/blog/what-is-openapi"><em>DocStar blog</em></a><em>. Try DocStar free:</em> <a href="https://docstar.io"><em>https://docstar.io</em></a></p>
]]></content:encoded></item></channel></rss>