Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mpx-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

mpx-api 🚀

Developer-first API testing, mocking, and documentation CLI.

No GUI. No proprietary formats. Just powerful, git-friendly API testing from your terminal.

Part of the Mesaplex developer toolchain.

Features

Git-friendly — Collections are YAML files, not proprietary blobs
CI/CD ready — Exit codes, JSON output, no GUI dependency
Beautiful terminal output with syntax highlighting
Request chaining — Use response data from one request in another
Built-in mock server — Test against OpenAPI specs without deploying (Pro)
Load testing — RPS control, percentile reporting (Pro)
Doc generation — Generate API docs from collections (Pro)
MCP server — Integrates with any MCP-compatible AI agent
Self-documenting — --schema returns machine-readable tool description

Installation

npm install -g mpx-api

Or run directly with npx:

npx mpx-api get https://api.github.com/users/octocat

Requirements: Node.js 18+ · No native dependencies · macOS, Linux, Windows

Quick Start

# Simple GET request
mpx-api get https://jsonplaceholder.typicode.com/users

# POST with JSON
mpx-api post https://api.example.com/users --json '{"name":"Alice"}'

# Custom headers
mpx-api get https://api.example.com/protected \
  -H "Authorization: Bearer $TOKEN"

# Verbose output (show headers)
mpx-api get https://httpbin.org/get -v

# Quiet mode (only response body)
mpx-api get https://api.example.com/data -q

Usage

HTTP Requests

Supports get, post, put, patch, delete, head, and options:

mpx-api get https://api.example.com/users
mpx-api post https://api.example.com/users --json '{"name":"Bob"}'
mpx-api put https://api.example.com/users/1 --json '{"name":"Alice"}'
mpx-api delete https://api.example.com/users/1

Collections

Collections are YAML files for repeatable API test suites:

# Initialize collection in your project
mpx-api collection init

# Add requests
mpx-api collection add get-users GET /users
mpx-api collection add create-user POST /users --json '{"name":"Bob"}'

# Run the collection
mpx-api collection run

Collection file format (.mpx-api/collection.yaml):

name: My API Tests
baseUrl: https://api.example.com

requests:
  - name: get-users
    method: GET
    url: /users
    headers:
      Authorization: Bearer {{env.API_TOKEN}}
    assert:
      status: 200
      body.length: { gt: 0 }
      responseTime: { lt: 500 }

  - name: get-specific-user
    method: GET
    url: /users/{{get-users.response.body[0].id}}
    assert:
      status: 200

Features: request chaining ({{request.response.body.id}}), environment variables ({{env.VAR}}), built-in assertions.

Environments

mpx-api env init                              # Create dev, staging, production
mpx-api env set staging API_URL=https://...   # Set variables
mpx-api env list                              # List environments
mpx-api collection run --env staging          # Run with environment

Testing & Assertions

mpx-api test ./collection.yaml
mpx-api test ./collection.yaml --env production
mpx-api test ./collection.yaml --json
mpx-api test ./collection.yaml --pdf report.pdf    # Export PDF report

Assertion operators: gt, lt, gte, lte, eq, ne, contains, exists

Request History

mpx-api history         # View recent requests
mpx-api history -n 50   # Last 50

Mock Server (Pro)

mpx-api mock ./openapi.yaml --port 4000

Load Testing (Pro)

mpx-api load https://api.example.com/health --rps 100 --duration 30s

Documentation Generation (Pro)

mpx-api docs ./collection.yaml --output API.md

AI Agent Usage

mpx-api is designed to be used by AI agents as well as humans.

JSON Output

Add --json to any command for structured, machine-readable output:

mpx-api get https://api.github.com/users/octocat --json

{
  "request": {
    "method": "GET",
    "url": "https://api.github.com/users/octocat",
    "headers": {},
    "body": null
  },
  "response": {
    "status": 200,
    "statusText": "OK",
    "headers": { "content-type": "application/json" },
    "body": { "login": "octocat" },
    "responseTime": 145,
    "size": 1234
  }
}

Schema Discovery

mpx-api --schema

Returns a complete JSON schema describing all commands, flags, inputs, outputs, and examples.

MCP Integration

Add to your MCP client configuration (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "mpx-api": {
      "command": "npx",
      "args": ["mpx-api", "mcp"]
    }
  }
}

The MCP server exposes these tools:

http_request — Send HTTP requests with full control over method, headers, body
get_schema — Get the complete tool schema for dynamic discovery

Exit Codes

Code	Meaning
0	Success (2xx or 3xx HTTP status)
1	Request failed or 4xx/5xx HTTP status

Automation Tips

Use --json for machine-parseable output
Use --quiet to suppress banners and progress info
Pipe output to jq for filtering
Check exit codes for pass/fail in CI/CD

CI/CD Integration

# .github/workflows/api-tests.yml
- name: Run API Tests
  run: npx mpx-api test ./tests/api-collection.yaml --env staging

Free vs Pro

Feature	Free	Pro
HTTP requests	✅	✅
Collections & chaining	✅	✅
Environments	✅	✅
Assertions & testing	✅	✅
JSON output	✅	✅
MCP server	✅	✅
Mock server	❌	✅
Load testing	❌	✅
Doc generation	❌	✅

Upgrade to Pro: https://mesaplex.com/mpx-api

License

Dual License — Free tier for personal use, Pro license for commercial use and advanced features. See LICENSE for full terms.

mpx-api