PreMan MCP

Turn your APIs into MCP tools that coding agents can discover, call, test, and audit.

PreMan is agent-first API infrastructure. It lets backend teams expose endpoints to AI coding agents through MCP, add an auth layer around those tools, and see exactly which agent called what.

Start

npm exec -y premanmcp@latest -- onboard

Create the account, verify the email, and get the PreMan app installed and opened already signed in. A bare preman in a terminal does the same thing.

Connect a coding agent

npm exec -y premanmcp@latest -- connect

Optional, and separate from starting out. Pick your coding agent from the list — Cursor, Claude Code, or Codex — and PreMan writes that agent's MCP config for you. No hand-edited config anywhere.

Local development form:

node bin/cli.js connect

First-time users are asked for an email and the code sent to it — no password: the terminal's credential is the pm_live_ key. Pass --password to also set one for dashboard sign-in, or set it later from the dashboard. PreMan creates or connects the account, generates an API key, saves it to ~/.preman/credentials.json, then writes a preman MCP server into the config your agent actually reads (~/.cursor/mcp.json, Claude Code's MCP config, or ~/.codex/config.toml):

{
  "mcpServers": {
    "preman": {
      "command": "npm",
      "args": ["exec", "-y", "premanmcp@latest", "--"],
      "env": {
        "PREMAN_BACKEND": "https://api.preman.live",
        "PREMAN_FRONTEND": "https://app.preman.live"
      }
    }
  }
}

connect reads the config back after writing it, and prints a copy-paste snippet if it cannot confirm the entry landed. Then it finishes the link itself rather than asking you to go restart anything, in cheapest-first order:

1. Self-test. It starts the MCP server exactly as your agent will and calls preman_status over stdio. That both completes the link and proves the whole chain — launcher, package, key, backend. --no-self-test turns it off.
2. Agent run, which also proves your agent can load what was written. For Cursor it runs cursor-agent mcp enable after writing mcp.json (new servers stay off the CLI approved list otherwise) and launches the agent with --approve-mcps so the check-in can actually call preman_status. It opens your agent interactively in a new terminal window — the session you go on to use — and falls back to a headless run (claude -p, cursor-agent --approve-mcps -p, codex exec) where no window can be opened, such as CI or SSH. --no-auto-checkin turns it off, PREMAN_NO_TERMINAL=1 keeps it headless.
3. Wait, if neither is possible: restart your agent and it links on its first call.

A self-test that answers from an unexpected backend is reported with the file that redirected it — a repo-local preman-mcp.config.json with "PREMAN_CONFIG_OVERRIDE": true wins over the MCP config env, and otherwise only fills in what the env leaves unset. When that file overrides PREMAN_BACKEND, the config connect wrote is still correct: the server reads that file only from the directory it starts in, so connect names the file and then retries from your home directory, where the override cannot reach it — self-test first, then your agent. Agents you start in the overriding directory keep using its backend, which is the point of the file.

Once linked, connect installs the git pre-push hook — so git push checks the endpoints you touched — prints what is left, and stops. It asks nothing. Everything else it used to run is its own command, because each one can fail on its own and none of them should hold up a link that already worked:

preman endpoints discover          # map this repo's endpoints
preman tests generate              # heuristic suites on saved Collections requests
preman tests review                # list flagged suites; --approve <id> enables schedule
preman tests setup                 # harvest path-param fixture IDs into a .env snippet
preman tests enrich                # optional LLM cases on remaining heuristic suites
preman runner start --background   # let PreMan apply fixes on this machine
preman github                      # or connect it in the dashboard
preman status                      # which of those are done

preman onboard (or setup, or a bare preman in a terminal) is what someone starting out runs: create the account and verify the email, then install the PreMan app and open it already signed in, then GitHub, AWS, Slack — one question per step, b to go back, and a summary at the end. Connecting a coding agent is no longer part of starting out; run preman connect when you actually want one wired into an IDE. connect --guide still runs the full pass inside connect itself: discovery, a first test, the runner, the desktop app and the integration prompts.

The app opens signed in because the CLI leaves the key it just minted in ~/.preman/desktop-session.json, which the app reads once and deletes. An app too old to look for it, or a machine that is not macOS, falls back to signing in on the app's own login screen with the account you just created.

Useful flags: --agent cursor|claude-code|codex skips the picker, --project writes project-local config, --print shows the config without writing it, --no-hook leaves push testing alone, and --no-guide connects and nothing else. With --guide, --yes takes every step's default without asking and --no-runner / --no-desktop / --no-integrations skip one each.

--yes deliberately does not install the desktop app: that step's default is no, because it downloads a hundred-odd megabytes and writes to /Applications. Run install-desktop when you want it.

In CI or any non-interactive shell, run connect --agent <name> --api-key pm_live_…. Without --agent there is nothing to prompt on, so connect prints ready-to-paste setup blocks for all three agents and exits 2.

preman install still exists and does the Cursor-only half of this.

Cloud dispatch (optional)

With a coding-agent credential saved — a Cursor API key from cursor.com/dashboard → Integrations → API Keys, or a Claude Code routine token and id from claude.ai/code/routines → your routine → Add API trigger — PreMan can start an agent run for you when it finds a failing endpoint, instead of handing back a prompt to paste.

connect asks for it once you are already set up, so skipping costs nothing. Come back to it any time:

npm exec -y premanmcp@latest -- dispatch

You can also create or connect your account first:

npm exec -y premanmcp@latest -- login

You can also pass the key directly:

npm exec -y premanmcp@latest -- connect --api-key pm_live_xxx

For project-local config:

npm exec -y premanmcp@latest -- connect --project

What It Does

• Converts API endpoints into agent-callable MCP tools.
• Migrates a Postman collection in one call (migrate_from_postman): keeps the assertions your pm.test blocks declared, splits the environment into shared variables and encrypted secrets, and schedules a monitored test suite per request.
• Creates/connects a PreMan account from the terminal or IDE agent.
• Lets agents test real backend endpoints from the IDE.
• Syncs endpoint inventory across backend and frontend workflows.
• Adds API-key auth for PreMan MCP access.
• Supports hosted MCPs with consumer tokens for customer-facing agent access.
• Records per-call observability so teams can audit which agent did what.
• Hands failing-endpoint alerts to your agent as fix tasks (preman_get_fix_task → repro curl → preman_complete_fix_task).
• Connects your production logs from the terminal (connect_logs): your agent asks where the logs live, then deploys a read-only CloudFormation role for AWS, or wires a shipper to the ingest endpoint for everything else.

Common Agent Commands

After installing, ask your coding agent:

Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet.

Use PreMan to sign me up, verify my email OTP, create my API key, then scan this project.

Use PreMan to test POST /auth/login.

Convert these endpoints into an MCP.

Show me the audit log for this hosted MCP.

Move my Postman collection over to PreMan.

Pull my pending PreMan fix tasks and fix the failing endpoint.

Connect my production logs to PreMan.

Cursor

npm exec -y premanmcp@latest -- connect --agent cursor

Manual Cursor config, if you would rather write it yourself:

{
  "mcpServers": {
    "preman": {
      "command": "npm",
      "args": ["exec", "-y", "premanmcp@latest", "--"]
    }
  }
}

Claude Code

npm exec -y premanmcp@latest -- connect --agent claude-code

Equivalent manual command:

claude mcp add preman -- npm exec -y premanmcp@latest --

Codex

npm exec -y premanmcp@latest -- connect --agent codex

Writes an [mcp_servers.preman] block into ~/.codex/config.toml.

CLI

npm exec -y premanmcp@latest -- connect            # Pick an agent and connect it
npm exec -y premanmcp@latest -- connect --agent codex   # Skip the picker
npm exec -y premanmcp@latest -- connect --project  # Write project-local config
npm exec -y premanmcp@latest -- connect --print    # Print config without writing
npm exec -y premanmcp@latest --         # Start the MCP server
npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API key
npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)

Push testing

preman hook install         # Write the pre-push hook (connect does this too)
preman hook status          # Installed? And does the command in it still answer?
preman hook repair          # Rewrite it if it stopped working (usually automatic)
preman hook uninstall       # Remove it, restoring any hook it replaced

The hook is generated shell that runs preman verify --pre-push and can only ever be advisory: no backend, no credentials, a crash or a timeout all exit 0 with a notice. Before writing it, install runs the command it is about to embed and requires an answer — a hook holding a preman that belongs to another package prints checks skipped at every push and looks installed forever. The embedded command is pinned to the version that wrote it rather than @latest, so upgrading us never changes what your pushes run; re-run hook install to move it. Set PREMAN_HOOK_INVOCATION to write a command of your own instead, and PREMAN_SKIP_HOOK=1 to silence the hook for a push.

You should not have to run repair. A hook of ours that stops answering is rewritten in the background by anything that proves PreMan runs here — any command, or your agent starting the MCP server — because nothing re-runs connect after an upgrade to notice, and the broken state is silent. It is narrow on purpose: a hook that still works keeps the version it pins, a hook we did not write is never touched, and no hook is installed where you never asked for one. The answer is remembered for an hour per directory, and PREMAN_NO_HOOK_REPAIR=1 turns it off.

Runner

preman onboard and connect --guide set this up for you; these are for managing it afterwards.

preman runner status              # Paired? Running?
preman runner start --background  # Hold the job stream, log to ~/.preman/runner.log
preman runner stop                # Stop it and report offline
preman runner register --agent claude-code   # Pair without starting

start pairs this machine itself when it is not paired yet, and re-pairs it when the backend has revoked the token it held, so neither is a command you have to be told to run. It works out which agent to pair as from the session it is running in, then from the agent PreMan is already configured in, then from the only one installed — and asks only when those disagree. Pass --agent cursor|claude-code|codex to settle it yourself, which is also what a machine with no terminal to ask in needs.

The runner holds one outbound connection to PreMan and runs the work PreMan queues for this machine — a failing endpoint becomes an agent run in your own repo instead of a prompt you have to paste. It is bound to the agent and directory it was registered with and refuses any job that names a different one. The agent may edit files; running commands needs --full-access (or PREMAN_RUNNER_FULL_ACCESS=1). Nothing runs until PreMan has something to fix, and preman runner stop ends it.

Options:

• --api-key <key>: PreMan API key.
• --backend <url>: PreMan backend URL. Defaults to https://api.preman.live.
• --frontend <url>: PreMan frontend URL. Defaults to https://app.preman.live.
• --name <name>: MCP server name. Defaults to preman.
• --project: Write .cursor/mcp.json in the current project.
• --skip-login: Install config without interactive terminal auth.
• --print: Print the generated MCP config without writing it.

Run a hosted MCP from the terminal

Installing the package also gives you a preman command. Once a selection is published as a hosted MCP, you can call its tools straight from a shell — same published selection, same consumer token, and same audit trail as an agent calling POST /h/<id>/mcp. Updating the selection updates the terminal; there is nothing to re-install.

preman link https://api.preman.live/h/<id>/mcp --env staging --token pm_hmcp_xxx
preman tools --env staging
preman run post_users_id_orders --env staging --arg id=42 --json '{"body":{"sku":"A1"}}'

link takes the URL straight from the deploy install snippet (a bare hosted MCP id works too, with --backend). Profiles are stored in ~/.preman/cli.json (mode 0600); --env <name> picks one. Tool names are the ones the runtime publishes — run preman tools to see them.

Run options:

• --env <name>: Profile to use. Falls back to PREMAN_MCP_URL, then the default profile.
• --arg key=value: String argument (repeatable). --arg key:=json sends a JSON-typed value.
• --json '{...}': Full arguments object. --json - reads it from stdin.
• --timeout <seconds>: Client-side timeout. Defaults to 60.
• --json-out: Print the raw JSON-RPC result.
• <tool> may be dotted — preman run staging.get_orders selects the profile inline.

Exit codes: 0 success, 1 the tool returned an error, 2 usage, 3 authentication, 4 JSON-RPC error (e.g. unknown tool), 5 network failure.

Environment Variables

• PREMAN_API_KEY: PreMan API key.
• PREMAN_BACKEND: PreMan backend URL.
• PREMAN_FRONTEND: PreMan frontend URL.
• PREMAN_MCP_URL: Hosted MCP endpoint (…/h/<id>/mcp) for preman run/preman tools when --env is omitted — useful in CI, where no profile file exists.
• PREMAN_MCP_TOKEN: Consumer token for PREMAN_MCP_URL.

If PREMAN_API_KEY is omitted, the MCP server loads credentials from ~/.preman/credentials.json.

Product

PreMan helps teams make APIs usable by agents without giving up control. Developers can turn endpoints into MCP servers, hand customers an install snippet or hosted MCP URL, and audit every tool call through PreMan.

Dashboard: https://app.preman.live

License

MIT