Recommend marketplace install; sync .mcp.json version

- README: make /plugin install postman@claude-plugins-official the primary
  install method; move GitHub and local-clone installs to collapsible alternatives
- .mcp.json: bump X-Plugin-Version and User-Agent to match plugin.json (were 1.2.0)
- release.yml: fail the release if .mcp.json version headers drift from plugin.json
- CLAUDE.md: document updating .mcp.json headers alongside plugin.json on release
- Bump plugin.json to 1.3.1 and add CHANGELOG entry

Co-Authored-By: Claude <noreply@anthropic.com>

Author: christosgkoros

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "postman",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Full API lifecycle management for Claude Code. Sync collections, generate client code, discover APIs, run tests, create mocks, publish docs, and audit security. Powered by the Postman MCP Server.",
   "author": {
     "name": "Postman",

.github/workflows/release.yml

@@ -26,6 +26,19 @@ jobs:
             exit 1
           fi
 
+      - name: Verify .mcp.json version matches plugin.json version
+        run: |
+          PLUGIN_VERSION=$(python -c "import json; print(json.load(open('.claude-plugin/plugin.json'))['version'])")
+          MCP_PLUGIN_VERSION=$(python -c "import json; print(json.load(open('.mcp.json'))['mcpServers']['postman']['headers']['X-Plugin-Version'])")
+          MCP_USER_AGENT=$(python -c "import json; print(json.load(open('.mcp.json'))['mcpServers']['postman']['headers']['User-Agent'])")
+          echo "plugin.json:            $PLUGIN_VERSION"
+          echo ".mcp.json X-Plugin-Version: $MCP_PLUGIN_VERSION"
+          echo ".mcp.json User-Agent:       $MCP_USER_AGENT"
+          if [ "$MCP_PLUGIN_VERSION" != "$PLUGIN_VERSION" ] || [ "$MCP_USER_AGENT" != "postman-claude-code-plugin/$PLUGIN_VERSION" ]; then
+            echo "::error::.mcp.json version headers do not match plugin.json version $PLUGIN_VERSION. Update X-Plugin-Version and User-Agent in .mcp.json before tagging."
+            exit 1
+          fi
+
       - name: Extract release notes from CHANGELOG
         id: notes
         run: |

.mcp.json

@@ -5,8 +5,8 @@
       "url": "https://mcp.postman.com/${POSTMAN_MCP_MODE:-mcp}",
       "headers": {
         "X-Source": "claude-code-plugin",
-        "X-Plugin-Version": "1.2.0",
-        "User-Agent": "postman-claude-code-plugin/1.2.0"
+        "X-Plugin-Version": "1.3.1",
+        "User-Agent": "postman-claude-code-plugin/1.3.1"
       }
     }
   }

CHANGELOG.md

@@ -10,6 +10,20 @@ is cut by tagging the matching `vX.Y.Z` (see [Releasing](#releasing)).
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-08-02
+
+### Changed
+
+- README now recommends installing from Anthropic's official plugin marketplace
+  (`/plugin install postman@claude-plugins-official`), with GitHub and local-clone
+  installs moved to collapsible alternatives.
+
+### Fixed
+
+- Bumped the `X-Plugin-Version` and `User-Agent` headers in `.mcp.json` to match
+  `plugin.json` (they had drifted to `1.2.0`). The release workflow now fails if
+  these versions ever fall out of sync again.
+
 ## [1.3.0] - 2026-07-20
 
 ### Added

CLAUDE.md

@@ -78,5 +78,6 @@ CLI commands work with Postman's git sync structure: `postman/collections/` (v3
 
 - The plugin follows [Semantic Versioning](https://semver.org). `version` in `.claude-plugin/plugin.json` is the single source of truth
 - Every user-facing change bumps the version and adds an entry under `## [Unreleased]` in `CHANGELOG.md` (added a command/skill → minor; fix/tweak → patch; breaking change → major)
-- To release: bump `plugin.json`, move `[Unreleased]` notes into a dated `## [X.Y.Z]` section, merge to `main`, then `git tag vX.Y.Z && git push origin vX.Y.Z`
-- The `Release` GitHub Actions workflow (`.github/workflows/release.yml`) triggers on `v*` tags: it fails if the tag doesn't match `plugin.json`, extracts the matching CHANGELOG section, and publishes a GitHub Release with those notes
+- When bumping `plugin.json`, also update the `X-Plugin-Version` and `User-Agent` headers in `.mcp.json` to the same version — these are sent to the Postman MCP Server for telemetry and must stay in sync
+- To release: bump `plugin.json` and the matching `.mcp.json` version headers, move `[Unreleased]` notes into a dated `## [X.Y.Z]` section, merge to `main`, then `git tag vX.Y.Z && git push origin vX.Y.Z`
+- The `Release` GitHub Actions workflow (`.github/workflows/release.yml`) triggers on `v*` tags: it fails if the tag doesn't match `plugin.json` or if `.mcp.json`'s version headers don't match `plugin.json`, extracts the matching CHANGELOG section, and publishes a GitHub Release with those notes

README.md

@@ -13,11 +13,27 @@ The Postman Plugin provides a single, simple install for Claude Code. It provide
 
 ## Installation
 
-Install directly from GitHub:
+Install from Anthropic's official plugin marketplace.
+
+In Claude Code:
+
+```
+/plugin install postman@claude-plugins-official
+```
+
+Or from the terminal:
+
+```bash
+claude plugin install postman@claude-plugins-official
+```
+
+<details>
+<summary>Alternative: install from GitHub</summary>
 
 ```bash
 claude plugin install github:Postman-Devrel/postman-claude-code-plugin
 ```
+</details>
 
 <details>
 <summary>Alternative: load from a local clone</summary>