credmcp

Credit-metered tools your coding agent installs, signs into, and pays for by itself. One npm package, two binaries: an invokable CLI and an MCP server.

npx credmcp init

That installs a skill into .claude/skills/, .codex/skills/, .cursor/skills/, .gemini/skills/ and .agents/skills/ with the setup steps written into it. Your agent reads them and does the rest.

The tools

| MCP tool | What it does | Cost | |---|---|---| | get_weather | Current conditions for a city or country | 100 credits | | create_note | Saves a note to your account | 50 credits | | get_balance | Remaining credits, prices, recent movements | free |

A new account is granted 1000 credits on first sign-in.

Setup

npx credmcp init       # install the agent instructions
npx credmcp login      # sign in with GitHub (opens a browser — run this yourself)
npx credmcp connect    # register the MCP server with this project
# reload your MCP client
npx credmcp verify     # confirm the whole chain works

login goes through auth.invokable.dev, which signs you in with GitHub. The token is stored at ~/.credmcp/config.json, directory 0700, file 0600.

Checking a connection

verify is the one to reach for when the tools do not appear. It starts the MCP server exactly as .mcp.json says to — which is what catches a stale path or a node that is not on the MCP client's PATH.

$ credmcp verify
  ✓ signed in              token from config
  ✓ api reachable          balance 500
  ✓ mcp registered         .mcp.json → /usr/local/bin/node
  ✓ mcp handshake          3 tools; get_balance returned 500.

It reports rather than fails — exit 0 with data.ok and a remediation on any failing check. Use --strict in CI to get a non-zero exit instead.

CLI commands

| Command | What it does | |---|---| | credmcp init | Install agent instructions into this project | | credmcp login / logout / whoami | Auth | | credmcp doctor | Diagnose config, connectivity and auth | | credmcp connect | Register the MCP server (.mcp.json, Cursor, VS Code) | | credmcp verify | Check the whole chain, including a live MCP tool call | | credmcp balance | Balance and prices — free | | credmcp weather --place <name> | Weather, with an approval gate — 100 credits | | credmcp note --text <text> | Save a note — 50 credits |

Every command takes --json and emits one JSON document on stdout with a semantic exit code. credmcp weather stops for approval before spending and exits 10; the approval is issued by the server and consumed exactly once.

Two binaries, on purpose

credmcp-mcp is a separate binary rather than a subcommand because @invokable/core diverts process.stdout.write to stderr while a command runs, so a stray console.log cannot corrupt the JSON document an agent parses. An MCP stdio server writes JSON-RPC to stdout for its whole lifetime, so the two contracts cannot share a process.

Environment

| Variable | Purpose | |---|---| | CREDMCP_API | Override the API origin (connect bakes this into .mcp.json) | | CREDMCP_AUTH | Override the auth server. Default https://auth.invokable.dev | | CREDMCP_TOKEN | Override the stored token | | CREDMCP_CONFIG_DIR | Override ~/.credmcp |

License

MIT