Back to Blog

Fixing Documentation with AI and the Sutram MCP Server

By Sergio Vieira Greve
Fixing Documentation with AI and the Sutram MCP Server

How we used the MCP Server to find, comment, fix, and version its own user guide — without leaving the terminal

The problem

We were configuring the Sutram MCP Server in Claude Code when the connection failed. The culprit? A wrong URL in the user guide. The documentation instructed users to connect to https://sutram.io/mcp, but the correct endpoint is https://app.sutram.io/mcp — the app. subdomain was missing.

A small typo, but one that would trip up every new user following the guide. The kind of bug that erodes trust in documentation.

Instead of opening the Sutram UI, downloading the file, searching and replacing, re-uploading, and managing versions manually, we decided to fix it the way we found it: through AI and MCP, right from the terminal.

The workflow

The entire fix was performed by Claude Code using the Sutram MCP Server tools — the same tools documented in the guide we were fixing. Here's what happened, step by step.

1. Find the document

The project organizes its documentation as records — folders with structured metadata (title, category, excerpt, publication date). Instead of navigating the folder tree level by level, the agent searched by metadata using sutram_search_folders:

{
  "conditions": [{"key": "title", "value": "MCP Server"}],
  "type": "file"
}

One call, one result: the MCP Server User Guide — a 69.5 KB markdown file, version 1, published, located at /en/Docs/User guides/sutram-mcp-server-user-guide.

2. Download and assess the damage

Using sutram_get_item to obtain a download URL, then fetching the file, the agent searched for all occurrences of the wrong URL:

10 occurrences of https://sutram.io/mcp
 0 occurrences of https://app.sutram.io/mcp

The error appeared everywhere: in the architecture diagram, in configuration examples for Claude Code, Cursor, and Claude Desktop, in the API reference section, and even in a Node.js code sample. Every single configuration snippet a user would copy-paste was broken.

3. Create a comment documenting the bug

Before making any changes, the agent created a markdown-anchored comment on the file using sutram_create_comment:

"Bug: The MCP server URL is incorrect throughout the document. All 9 occurrences show https://sutram.io/mcp but the correct URL is https://app.sutram.io/mcp (missing app. subdomain). This causes connection failures when users follow the guide."

The comment was anchored directly to the first occurrence of the URL in the text — not a generic file-level note, but a precise pointer to the problem.

4. Create a new version and check out for editing

The file was published (v1), so direct editing was not possible. The versioning workflow required two steps:

  1. sutram_create_new_version — created version 2 in draft status
  2. sutram_checkout_file — locked the file for exclusive editing

This is the same workflow that engineering teams use for controlled document revisions: no one else can modify the file while it's checked out.

5. Fix and upload the corrected file

The agent performed a global find-and-replace:

https://sutram.io/mcp → https://app.sutram.io/mcp

All 10 occurrences replaced. Then, the upload followed the standard three-step flow:

  1. sutram_request_upload — obtained a presigned S3 URL
  2. HTTP PUT — uploaded the corrected file directly to S3
  3. sutram_upload_modified_file — registered the new content with Sutram

6. Check in and publish

With the file uploaded:

  • sutram_checkin_file — released the lock, making the file available again
  • sutram_publish_version — promoted version 2 from draft to published

The version history now shows both versions: v1 (the original with the wrong URLs) and v2 (the corrected version), both preserved for audit.

7. Resolve the comment

Finally, sutram_resolve_comment marked the bug comment as resolved. The comment remains visible in the file's history — anyone reviewing the document can see what was wrong and when it was fixed.

The tools used

Tool Purpose
sutram_search_folders Find the document by metadata
sutram_get_item Get file metadata and download URL
sutram_create_comment Document the bug with a markdown-anchored comment
sutram_create_new_version Create v2 draft from published v1
sutram_checkout_file Lock the file for exclusive editing
sutram_request_upload Get presigned URL for S3 upload
sutram_upload_modified_file Register the corrected file
sutram_checkin_file Release the editing lock
sutram_publish_version Publish v2
sutram_resolve_comment Close the bug comment

Ten different MCP tools, orchestrated in sequence by the AI agent, each performing a specific step in a professional document management workflow.

Why this matters

This wasn't a demo or a proof of concept. It was a real bug, found in production documentation, that was causing real connection failures for users trying to set up the MCP Server.

What makes it interesting is the closed loop: the MCP Server's own tools were used to fix the MCP Server's own documentation. The agent used the same versioning, commenting, and file management capabilities that the guide describes — proving they work exactly as documented (once you have the right URL, of course).

The entire fix — from discovery to published correction — took about 2 minutes and never left the terminal. No browser tabs, no manual file downloads, no copy-pasting between editors. Just an AI agent, MCP tools, and a conversation.

The bigger picture

Documentation bugs are uniquely insidious. They sit in files that rarely get the same review rigor as code. They break onboarding. They generate support tickets. And they tend to persist because fixing them feels like a low-priority chore.

MCP changes the economics of documentation maintenance. When an AI agent can navigate a content repository, identify issues, apply fixes through proper version control, and document the changes — all within the same conversation where the bug was discovered — the barrier to fixing documentation drops to nearly zero.

Back to Blog