pinion-os

Pinion OS provides a Node.js SDK and a set of MCP-compatible endpoints to enable x402 payments and on-chain skills for your app or Claude agent. The server handles signing, payment negotiation, and verification with a facilitator, allowing your code or agent to call into skill endpoints without manually managing payments. The MCP plugin exposes twelve tools such as pinion_balance, pinion_price, pinion_wallet, pinion_chat, pinion_send, pinion_trade, pinion_fund, pinion_pay_service, pinion_spend_limit, pinion_unlimited, and pinion_unlimited_verify. You can run the server directly via npx pinion-os or use it as an MCP plugin for Claude, enabling your agent to query balances, look up prices, manage wallets, chat with the agent, execute token transfers, perform trades, fund wallets, and access paid external services using x402 payments.

Prerequisites:

• Node.js installed (recommended latest LTS)
• npm or pnpm available

Installation steps:

1. Install the Pinion OS package from npm:

npm install pinion-os

2. Ensure you have a wallet private key with ETH for gas and USDC for Base payments. Set the environment variable PINION_PRIVATE_KEY when running tools that require authentication:

export PINION_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

3. Start using Pinion OS in code or via MCP plugin:

• In code:

node -e "import('pinion-os').then(async ({ PinionClient }) => {
  const p = new PinionClient({ privateKey: process.env.PINION_PRIVATE_KEY });
  console.log(await p.skills.price('ETH'));
})"

• As MCP server (via npx):

npx pinion-os

4. If you plan to embed as Claude MCP plugin, configure the MCP host with npx pinion-os and provide PINION_PRIVATE_KEY when prompted.

Notes and tips:

• The server operates on Base network with x402 payments. Each server call may incur a small USDC cost settled automatically.
• Set PINION_PRIVATE_KEY in your environment to enable wallet-based signing. Without it, some operations may be unavailable.
• The MCP config example positions the Pinion MSP under the key 'pinion', but you can rename it as needed for your MCP host. The command typically uses npx pinion-os; you can also run with a fully specified node path if needed.
• For Claude Desktop or Cursor IDE integration, ensure the env var is provided in the respective config files or startup scripts so the agent can sign and authorize payments.
• The SDK supports both direct usage (pinion.skills.*) and payX402Service for calling external x402 endpoints. Ensure your external services accept x402 payments and respond within the expected payload contracts.
• If you upgrade or change the server, verify compatibility of the x402 version and any dependent express adapters (v1 or v2) used by your skill servers.