Setup mcpdev
ActionsCLI documentation: phillarmonic.github.io/mcpdev
A GitHub Action to install and setup the mcpdev cli - a direct CLI for MCP servers over stdio and Streamable HTTP.
mcpdev inspects, invokes, snapshots, diffs, and replays MCP servers. It was built as a local debugging tool, but the same interface contract checks are useful in CI: a workflow can inspect a server, compare its catalog against a committed baseline, and fail the build when a tool disappears. This action puts the release binary on PATH so those checks run against the exact build the release published.
- Cross-platform support: Linux, macOS, and Windows
- Multi-architecture: AMD64 and ARM64
- Checksum verification: every archive is matched against the release
SHA256SUMS - Version flexibility: install latest or a specific tag
- Major version pinning: resolve
v0orv0.1to the newest matching release - Caching support: cache the installed binary for faster builds
- GitHub token support: avoid API rate limiting
- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
with:
version: 'v0.1.0'- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
with:
version: 'v0'This resolves to the newest stable v0.x.y release. Prefixes with two components also work: v0.1 resolves to the newest v0.1.y release.
- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
with:
version: 'latest'
cache: 'false'- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}| Input | Description | Required | Default |
|---|---|---|---|
version |
Version of mcpdev to install (e.g., "v0", "v0.1.0", "latest") | No | latest |
token |
GitHub token for API requests (to avoid rate limiting) | No | ${{ github.token }} |
cache |
Enable caching of downloaded binaries | No | true |
| Output | Description |
|---|---|
version |
The version of mcpdev that was installed |
path |
Path to the installed mcpdev binary |
cache-hit |
Whether the binary was restored from cache |
version is the string the binary reports, without the leading v (for example 0.1.0).
name: MCP contract
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
contract:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v7
- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
id: mcpdev
- name: Show mcpdev info
run: |
echo "Installed version: ${{ steps.mcpdev.outputs.version }}"
echo "Binary path: ${{ steps.mcpdev.outputs.path }}"
echo "Cache hit: ${{ steps.mcpdev.outputs.cache-hit }}"
mcpdev --format json version
- name: Inspect the server under test
run: mcpdev inspect tools --command ./bin/my-mcp-servername: Multi-platform MCP checks
on: [push, pull_request]
jobs:
test:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- name: Checkout code
uses: actions/checkout@v7
- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
- name: Inspect the server under test
run: mcpdev inspect tools --command ./bin/my-mcp-serverCommit a snapshot of the server catalog and fail the build when the interface changes beyond the policy you allow.
name: Interface baseline
on: [pull_request]
jobs:
baseline:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v7
- name: Setup mcpdev
uses: phillarmonic/setup-mcpdev@v1
- name: Capture the current interface
run: mcpdev snapshot --command ./bin/my-mcp-server --out contract.json
- name: Compare against the committed baseline
run: mcpdev diff --from .mcpdev/baseline.json --to contract.json --fail-on breaking--fail-on accepts metadata, additive, or breaking. A triggering change exits with class 40.
name: Version matrix
on: [workflow_dispatch]
jobs:
test:
strategy:
fail-fast: false
matrix:
mcpdev-version: ['v0.1.0', 'v0', 'latest']
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- name: Checkout code
uses: actions/checkout@v7
- name: Setup mcpdev ${{ matrix.mcpdev-version }}
uses: phillarmonic/setup-mcpdev@v1
with:
version: ${{ matrix.mcpdev-version }}
- name: Test with mcpdev
run: mcpdev version| OS | Architecture | Status |
|---|---|---|
| Linux | AMD64 | Supported |
| Linux | ARM64 | Supported |
| macOS | AMD64 | Supported |
| macOS | ARM64 | Supported |
| Windows | AMD64 | Supported |
| Windows | ARM64 | Supported |
mcpdev publishes one archive per target:
mcpdev_<version>_<os>_<arch>.tar.gzfor Linux and macOSmcpdev_<version>_<os>_<arch>.zipfor Windows
Each archive holds a single binary (mcpdev or mcpdev.exe). The action downloads the matching archive and SHA256SUMS, checks the digest, unpacks the binary into ${{ runner.temp }}/mcpdev-bin, and adds that directory to PATH.
The installed binary is then checked with mcpdev --format json version, which must report the version that was requested. A release tag and its stamped archive cannot drift without failing the step.
The action caches the installed binary under a key built from the mcpdev version and the runner platform. Repeating a job restores the binary instead of downloading it again.
To disable caching, set the cache input to 'false'.
The action uses the GitHub API to fetch release information. To avoid rate limiting:
- The action uses
${{ github.token }}by default - For higher rate limits, provide a custom token via the
tokeninput
If you see "mcpdev: command not found":
- Check that the action completed successfully
- Verify the platform is supported
- Check the GitHub Actions logs for download or checksum errors
If the action reports a checksum mismatch:
- Confirm the release is intact on the releases page
- Report the release instead of working around the check, since the archive and
SHA256SUMSno longer agree
If you encounter GitHub API rate limiting:
- Provide a GitHub token via the
tokeninput - Use a specific version instead of "latest" to reduce API calls
If a specific version is not found:
- Check available releases: https://github.com/phillarmonic/mcpdev/releases
- Ensure the version format is correct (e.g., "v0.1.0")
- Use "latest" to get the most recent release
The action is versioned separately from mcpdev. v1 tracks the newest 1.x action release and is what the examples pin. For a fully reproducible workflow, pin the exact tag (v1.0.0).
The version input selects the mcpdev release independently from the action tag, so new action code can install an older mcpdev build when you need that.
Issues and pull requests are welcome! Please see the main repository for contribution guidelines.
This action is distributed under the same license as mcpdev. See the LICENSE file for details.
Setup mcpdev is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.