Blog post and documentation changes for Remote MCP #16168

Clear explanation of the evolution from local to remote MCP server
Good technical details about OAuth authentication flow
Excellent real-world Neo examples with concrete use cases
Well-structured progression from discovery → code generation → autonomous automation

Issues:

Line 27 - Inconsistent note formatting. The style guide doesn't mention using > blockquotes for notes. According to STYLE-GUIDE.md, notes should use the {{% notes type="..." %}} shortcode. Current text:

> **Note:** The local MCP server continues to be available...

Should be:

{{% notes type="info" %}}
The local MCP server continues to be available and fully supported for developers who prefer local tooling or need offline capabilities.
{{% /notes %}}

Lines 117-118 - Formatting inconsistency. The bold text example should not be bolded as it's meant to be a user prompt, not emphasis. Consider using regular text or code formatting instead.
Line 102 - The description says Neo is "an AI that ships infrastructure changes autonomously" but this might be misleading since Neo still requires human approval for PRs (as mentioned in line 113 "Human-in-the-loop"). Consider clarifying that Neo prepares and proposes changes autonomously.
Technical accuracy check needed: Can you confirm that the Remote MCP Server at https://mcp.ai.pulumi.com/mcp is actually live and accessible? This is crucial for the blog post announcement.

Documentation (`content/docs/iac/using-pulumi/mcp-server/index.md`)

Strengths:

Comprehensive coverage of all supported AI assistants
Detailed tool documentation with clear descriptions
Good troubleshooting section
Proper alias configured for the URL migration (/docs/iac/using-pulumi/mcp-server/)

Issues:

Line 14 - The alias list is actually correct (it preserves the old URL path). Good job on this.
Line 17 - Good update to mention Neo integration upfront.
Line 110 - Windsurf configuration format looks different from other assistants. Can you verify this is the correct format? Other assistants use transport and url fields, but Windsurf uses serverUrl. Is this confirmed correct for Windsurf?
Line 163 - The deploy-to-aws tool is listed, but there's no explanation of what "automatically analyzes your application files" means. Does it scan the directory? Does it require specific file types? This needs clarification.

Modified blog post (`content/blog/mcp-server-ai-assistants/index.md`)

Changes:

Updated Cursor installation from local npm package to remote server URL ✅
Updated link text from "visiting the following link" to "clicking the following button" (more accurate) ✅
Removed screenshot of Cursor MCP settings validation (presumably outdated with remote setup) ✅
Updated link to MCP docs from absolute to relative URL ✅

These changes look good and align with the remote MCP migration.

Content quality and clarity

Blog post strengths:

Excellent narrative structure with clear value propositions
Strong opening that contextualizes the evolution
Real-world examples are specific and compelling
"Real-World Workflow" section provides concrete understanding

Documentation strengths:

Comprehensive AI assistant coverage
Clear step-by-step instructions
Excellent examples section with realistic use cases
Good balance between reference and tutorial content

Suggestions:

Blog post line 49 - "Enter your Pulumi Access Token (which is validated server-side)" - Consider adding a security note about token handling/storage. Users might be concerned about entering tokens in a browser popup.
Documentation line 229 - "Delegate to Neo for tasks that require:" - This list is good, but consider adding an example of what NOT to delegate to Neo (e.g., simple queries, one-off resource lookups).
Both files - The OAuth flow description is mentioned but could benefit from a note about token expiration/refresh. Do users need to re-authenticate periodically?

Style guide compliance

Headings: ✅ All correct

Blog H1: "Announcing Pulumi Remote MCP Server" (Title Case) ✅
Blog H2s: "The Evolution of Pulumi MCP", "Why Remote MCP?" etc. (Title Case - appropriate for blog post) ✅
Docs H1: "Pulumi Model Context Protocol server" (in frontmatter) ✅
Docs H2+: Sentence case ✅

Lists: ✅ The ordered lists don't all use 1. format, but most lists in this content are unordered, which is appropriate.

Capitalization: ✅ Generally good. Proper nouns capitalized correctly (Pulumi, Neo, Claude, Cursor, etc.). Common nouns like "stack" are lowercased. ✅

Links: ✅ Descriptive link text throughout, no "click here" or vague references.

Tone: ✅ Professional and clear, avoids "easy" or "simple".

Line breaks: ⚠️ Some paragraphs could be shortened for better readability (see blog lines 104-113, which is a long 6-bullet list that could be broken up), but overall acceptable.

Migration checklist

Old single-file docs replaced with page bundle (to support images)
Alias configured correctly in new location
Old file deleted
Images added to bundle directory
Blog post updated with new remote MCP link
New blog post created announcing remote MCP
Meta image added for new blog post

Summary

This PR successfully migrates the MCP documentation to support the Remote MCP Server launch. The technical content is accurate and comprehensive, with excellent real-world examples. The main issues are:

Critical: Verify the remote MCP server URL is live before merging
Style: Convert blockquote note to proper notes shortcode (line 27 of blog post)
Clarification needed: Windsurf config format, deploy-to-aws tool behavior
Minor: Consider security note about token handling in OAuth flow

The content is well-written, properly structured, and follows the style guide. Great job on the comprehensive documentation and compelling blog post! 🎉

Job Run | Branch: arturl/remote-mcp

claude · 2025-10-06T14:22:39Z

Pull Request Review

Thank you for this comprehensive update on the Remote MCP Server! Overall, this is strong content with good structure and clear explanations. I've identified several issues that need attention before merging.

Critical Issues

1. Typo in PR description

Issue: "Changs for remote MCP" should be "Changes for remote MCP"

2. Missing newline at end of file

File: content/blog/remote-mcp-server/index.md (line 194)
Issue: File must end with a newline per repository standards.

3. Incomplete file in documentation

File: content/docs/iac/using-pulumi/mcp-server/index.md (line 85)
Issue: The Claude Desktop configuration section appears truncated in the diff. Please verify the full file was committed correctly.

Style and Content Issues

4. Vague language

File: content/blog/remote-mcp-server/index.md (lines 21, 25)
Issue: Phrases like "The adoption and feedback...has been positive" are vague. Be specific about metrics or concrete benefits if possible.

5. Avoid "simply"

File: content/blog/remote-mcp-server/index.md (line 35)
Issue: "you simply configure" — Avoid words like "simply" per STYLE-GUIDE.md as they judge difficulty.
Suggestion: "you configure your AI assistant"

6. Passive voice

File: content/blog/remote-mcp-server/index.md (line 49)
Issue: "which is validated server-side" — Use active voice.
Suggestion: "which the server validates"

7. Run-on sentence

File: content/blog/remote-mcp-server/index.md (line 154)
Issue: Long sentence could be split for clarity.

8. Inconsistent code formatting

File: content/blog/remote-mcp-server/index.md (lines 65-67, 71-72)
Issue: Tool names formatted as code inconsistently throughout document.

9. Repetitive structure

File: content/blog/remote-mcp-server/index.md (lines 120-147)
Issue: Three consecutive examples use the same "Neo will:" list structure. Vary formatting for readability.

10. Unclear instructions

File: content/docs/iac/using-pulumi/mcp-server/index.md (lines 67-71)
Issue: Numbered list describes "After adding configuration" but some steps may happen during setup. Clarify sequence.

Recommendations

11. Verify links

Please confirm these internal links work:

/docs/pulumi-cloud/neo/
/docs/iac/using-pulumi/mcp-server/
/docs/pulumi-cloud/cloud-rest-api/

12. Verify image

File: content/docs/iac/using-pulumi/mcp-server/index.md (line 88)
Issue: Verify claude-desktop-setup.png exists and displays correctly.

13. Alias correctly added

Good work: The alias for the moved file is correctly added (line 13-14).

Summary

Must Fix:

Issue Update in the wake of renamepocalypse #2: Add newline at end of content/blog/remote-mcp-server/index.md
Issue Improve our TypeScript documentation story #3: Fix truncated documentation file
Issue Switch to using typedoc for TypeScript documentation. #1: Fix typo in PR description

Strongly Recommended:

Issues Quickstart for LM release #4-9: Address style and clarity issues
Issues have a way to "fold" long code/output in our docs #11-12: Verify links and images

Overall, this is excellent content that will be helpful for users. Once the critical issues are addressed, this will be ready to merge!

content/blog/remote-mcp-server/index.md

kramhuber

I only reviewed the blog post. I'll defer the docs to @CamSoper

content/blog/remote-mcp-server/index.md

pulumi-bot · 2025-10-07T02:31:17Z

Your site preview for commit cbf00a5 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16168-cbf00a52.s3-website.us-west-2.amazonaws.com.

CamSoper

No notes, LGTM!

Remote MCP - doc initial change

b2acc2f

arturl temporarily deployed to testing October 4, 2025 01:17 — with GitHub Actions Inactive

arturl changed the title ~~Remote MCP - doc initial change~~ Blog post and documentation changes for Remote MCP Oct 4, 2025

arturl added 2 commits October 3, 2025 18:27

blog placeholder

c79d789

Minor fixes suggested by PR

9468477

arturl had a problem deploying to testing October 4, 2025 01:38 — with GitHub Actions Failure

arturl had a problem deploying to testing October 4, 2025 01:44 — with GitHub Actions Failure

arturl had a problem deploying to testing October 4, 2025 02:11 — with GitHub Actions Failure

blog post update

fbbebac

arturl had a problem deploying to testing October 4, 2025 02:34 — with GitHub Actions Failure

Create meta.png

471bf06

arturl temporarily deployed to testing October 4, 2025 02:47 — with GitHub Actions Inactive

Updates based on self-review

8714e49

arturl temporarily deployed to testing October 4, 2025 03:12 — with GitHub Actions Inactive

Convert to bundle to allow images

94aa0e2

arturl temporarily deployed to testing October 4, 2025 03:57 — with GitHub Actions Inactive

arturl requested review from dirien, mikhailshilkov and vova-ivanov October 4, 2025 04:00

pulumi deleted a comment from claude bot Oct 4, 2025

arturl added 2 commits October 5, 2025 22:14

Add an alias

8f310af

Change text capitalization style

d133bf4

arturl temporarily deployed to testing October 6, 2025 05:15 — with GitHub Actions Inactive

pulumi deleted a comment from claude bot Oct 6, 2025

arturl marked this pull request as ready for review October 6, 2025 14:20

arturl requested review from komalali, kramhuber and meagancojocar October 6, 2025 14:20

kramhuber requested a review from CamSoper October 7, 2025 00:54

kramhuber reviewed Oct 7, 2025

View reviewed changes

content/blog/remote-mcp-server/index.md Outdated Show resolved Hide resolved

kramhuber reviewed Oct 7, 2025

View reviewed changes

content/blog/remote-mcp-server/index.md Outdated Show resolved Hide resolved

kramhuber approved these changes Oct 7, 2025

View reviewed changes

content/blog/remote-mcp-server/index.md Show resolved Hide resolved

content/blog/remote-mcp-server/index.md Outdated Show resolved Hide resolved

content/blog/remote-mcp-server/index.md Show resolved Hide resolved

PR feedback from Mark

cbf00a5

arturl temporarily deployed to testing October 7, 2025 02:23 — with GitHub Actions Inactive

CamSoper approved these changes Oct 7, 2025

View reviewed changes

arturl merged commit c985856 into master Oct 7, 2025
15 checks passed

arturl deleted the arturl/remote-mcp branch October 7, 2025 16:14

arturl temporarily deployed to testing October 7, 2025 16:14 — with GitHub Actions Inactive

Blog post and documentation changes for Remote MCP #16168

Blog post and documentation changes for Remote MCP #16168

Uh oh!

Conversation

arturl commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pulumi-bot commented Oct 4, 2025

Uh oh!

pulumi-bot commented Oct 4, 2025

Uh oh!

pulumi-bot commented Oct 4, 2025

Uh oh!

arturl commented Oct 4, 2025

Uh oh!

pulumi-bot commented Oct 4, 2025

Uh oh!

pulumi-bot commented Oct 6, 2025

Uh oh!

arturl commented Oct 6, 2025

Uh oh!

claude bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Remote MCP Changes

Tasks

Technical accuracy

New blog post (content/blog/remote-mcp-server/index.md)

Documentation (content/docs/iac/using-pulumi/mcp-server/index.md)

Modified blog post (content/blog/mcp-server-ai-assistants/index.md)

Content quality and clarity

Style guide compliance

Migration checklist

Summary

Uh oh!

claude bot commented Oct 6, 2025

Pull Request Review

Critical Issues

1. Typo in PR description

2. Missing newline at end of file

3. Incomplete file in documentation

Style and Content Issues

4. Vague language

5. Avoid "simply"

6. Passive voice

7. Run-on sentence

8. Inconsistent code formatting

9. Repetitive structure

10. Unclear instructions

Recommendations

11. Verify links

12. Verify image

13. Alias correctly added

Summary

Uh oh!

Uh oh!

Uh oh!

kramhuber left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pulumi-bot commented Oct 7, 2025

Uh oh!

CamSoper left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

arturl commented Oct 4, 2025 •

edited

Loading

claude bot commented Oct 6, 2025 •

edited

Loading

New blog post (`content/blog/remote-mcp-server/index.md`)

Documentation (`content/docs/iac/using-pulumi/mcp-server/index.md`)

Modified blog post (`content/blog/mcp-server-ai-assistants/index.md`)