docs: route per-agent setup to the install guide, and correct the registry record

[christosgkoros]

Reworked. The first version of this PR duplicated the full per-agent command matrix into the README. That was the wrong call and this PR now does the opposite — see Why the approach changed.

Summary

The Supported agents and IDEs table pointed all 9 clients at learning.postman.com and carried no per-agent detail, so a reader had to guess which of the two Quick start paths applied to their tool. The intro also still advertised Gemini CLI, which was removed from the supported set.

README — keep Quick start as the generic, always-completable path (remote URL or npx), and route the per-agent specifics to the install guide:

• Per-agent deep links to the guide's #install-<agent> anchors, with columns showing whether a one-click install and a Postman plugin / extension / power exist for that agent.
• UTM params on those links, so search → install attribution survives the hop from GitHub.
• The "IDE-specific setup" line now points at the guide rather than the table beneath it.
• Gemini CLI dropped from the intro.

server.json — the registry record feeds the MCP client install UIs and pulsemcp, lobehub, glama, cursor.directory and mcpservers.com, so these fields are what a discovering agent or catalog actually reads:

• description was "A basic MCP server to operate on the Postman API." — says nothing about what the server does. Replaced with a capability-led line, 93 chars against the schema's 100 cap.
• title added, so subregistries have a display name.
• websiteUrl was unset. The schema calls it out as "particularly useful when the server has custom installation instructions", which is exactly this server. This is the field that sends registry and aggregator traffic to a surface we control and can measure.
• remotes gained /code and /learn for US and EU. Only /mcp and /minimal were listed, so two of the four toolsets were invisible to anything discovering the server through the registry.
• Authorization isRequired was true on every endpoint, contradicting OAuth. Now false for US (OAuth needs no API key) and true for EU, which is API-key only.

Version, package identifiers and fileSha256 are untouched — those belong to the release workflow.

Why the approach changed

The original version put the resolved commands for all 9 agents directly in the README. Two problems with that:

1. It does not help postman.com's SEO. GitHub renders rel="nofollow" on every outbound README link — verified, all 35 of them. Nothing accrues to the product page. A better-ranking README helps github.com, which already ranks.
2. It works against the funnel. A self-sufficient README means the install completes on a surface with no one-click buttons, no toolset/region toggles, no telemetry-consent flow, and no instrumentation. First tool invocation is still measurable server-side at mcp.postman.com, but the attribution back to a search entry is lost — and that funnel is being built.

There is a real cost to the other extreme too: an agent that cannot complete an install from the README may fall back to a third party rather than fetch the page. In a SERP check on 2026-08-05, "postman mcp server config cursor" produced an answer that ended by telling the user to click "Connect next to Composio."

So this lands in the middle: Quick start stays generic and always completable, so no agent is ever stranded; per-agent specifics route to the guide, which is where the one-click buttons and live command rewriting are. The #install-<agent> anchors these links target are new — they ship in marketing-site PR #3321, which makes the per-agent install content server-rendered for the first time.

Issue

None

Stakeholder

@christosgkoros

Assignees

None

Preview

N/A — no preview deploy in this repo. Rendered README on the branch: https://github.com/postmanlabs/postman-mcp-server/blob/docs/readme-per-agent-install-commands/README.md

How to test

• Read the rendered README and confirm Quick start still gives a complete, runnable path for both remote and local without leaving the page
• Confirm all 9 per-agent links resolve, and that the One-click / Plugin columns match reality for each agent
• Confirm the Authorization isRequired: false claim for US remotes matches server behaviour (OAuth without an API key)
• npx ajv-cli validate -s https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json -d server.json --strict=false

Test with Claude

Check out the `docs/readme-per-agent-install-commands` branch of postmanlabs/postman-mcp-server. Verify the README still lets a reader complete an install without leaving the file: the Quick start section must contain both a remote URL and a runnable npx command. Then confirm the "Supported agents and IDEs" table lists all 9 agents, that each links to a #install-<agent> anchor on www.postman.com/product/mcp-server/ carrying UTM params, and that the intro no longer mentions Gemini CLI. Report pass/fail with the agents and links you checked.

Still on that branch, review server.json against https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json. Confirm description is under the 100-character cap, websiteUrl and title are valid top-level fields, all four toolsets (/minimal, /code, /mcp, /learn) appear as remotes for both mcp.postman.com and mcp.eu.postman.com, and Authorization isRequired is false only for the US endpoints and true for the EU ones. Then confirm nothing owned by the release workflow changed — version, package identifiers and fileSha256 must match main. Report pass/fail with the fields you compared.

Launch date

N/A

Checklist

• server.json validated against the published MCP schema
• Quick start remains a complete, standalone install path
• Per-agent links carry UTM params for funnel attribution
• Authorization isRequired change confirmed against server behaviour by a maintainer
• #install-<agent> anchors live — depends on marketing-site #3321 shipping first
• Kept as a draft while in progress; marked ready for review when it's ready

Reviewer note on ordering

The per-agent links point at anchors that do not exist on production yet. Merge #3321 first, or the 9 table links will land at the top of the install guide rather than the relevant agent. Everything else here is independent.

Generated with Claude Code