Recommend marketplace install; keep .mcp.json version in sync

.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/CODEOWNERS

@@ -0,0 +1,13 @@
+# Code owners / default PR reviewers.
+#
+# GitHub auto-requests these reviewers when a pull request is opened as — or
+# marked — "ready for review". Draft PRs do not trigger a request.
+#
+# These are the individual members of the @postman-eng/postman-api team. The
+# team itself cannot be referenced here: CODEOWNERS only supports teams that
+# belong to the same org as the repo (Postman-Devrel), and postman-api lives in
+# the postman-eng org. Keep this list in sync with that team manually.
+#
+# NOTE: Each user must have at least read access to this repo, otherwise GitHub
+# silently skips them as a code owner.
+* @akira28 @garciasdos @christosgkoros @shruti-paranjape @alexander-rubia @rubenbaraut

.github/workflows/plugin-checks.yml

@@ -57,3 +57,24 @@ jobs:
         with:
           python-version: "3.12"
       - run: python .github/scripts/validate-structure.py
+
+  version-sync:
+    name: Version Sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - 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 to match plugin.json."
+            exit 1
+          fi

.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>