kushbitx-mcp-agent

A real agent-directed integration for @kushbitx/sdk — built for the KushBitx bounty issue #1.

The model decides which SDK tool to call and in what order. It is not a fixed-sequence demo script: the agent receives three tool schemas, emits tool_calls, reads the results, and chooses when to stop. The same three capabilities are also exposed as an MCP stdio server so any MCP host can drive them.

What changed in this revision

This revision answers the three points in the maintainer's technical review:

Related MCP server: x402farm-mcp

Security posture

Layout

agent/
  tools.mjs          # three tool schemas + SDK-backed handlers (the single source of truth)
  agent.mjs          # [OI]-compatible tool-calling AGENT LOOP (the model chooses the calls)
src/
  server.mjs         # MCP stdio server exposing the same three tools
  retry.mjs          # bounded retry for transient upstream signals only
test/
  tools.test.mjs     # tool layer: happy paths, validation, failures, retry, no-signing guard
  server.test.mjs    # MCP adapter contract + error-result behaviour
evidence/
  agent-run.md       # sanitized transcript of a real agent-directed run
  agent-transcript.json

Tools exposed

Requirements

• Node.js 22 or later (tested on v22.23.1)

• No wallet, no funds, and no API key to KushBitx are required for the free path

Setup

git clone https://github.com/krpx0341/kushbitx-mcp-agent
cd kushbitx-mcp-agent
npm install

Run the tests

npm test

Expected: # tests 18 / # pass 18 / # fail 0. All tests are offline — the SDK's fetchFn injection seam is used, so no network or credentials are needed.

Run the agent

The agent needs an [OI]-compatible chat-completions endpoint. Point it at any provider that supports tool calling:

export OPENAI_BASE_URL="https://your-endpoint/v1"
export OPENAI_API_KEY="your-key"
export AGENT_MODEL="your-model"
npm run agent

To capture the full tool-call transcript:

export AGENT_TRANSCRIPT_OUT="./evidence/agent-transcript.json"
npm run agent

The agent prints every tool call with its arguments and result, then a summary. It exits non-zero if the three-tool checklist was not completed, so CI can catch a regression.

Using the MCP server from another host

{
  "mcpServers": {
    "kushbitx": {
      "command": "node",
      "args": ["/absolute/path/to/kushbitx-mcp-agent/src/server.mjs"]
    }
  }
}

Verified output

From the committed run — full detail in evidence/agent-run.md:

======================================================================
Summary
======================================================================
turns used        : 2
tool calls        : 3
distinct tools    : preview_token, evaluate_spend, get_payment_challenge
tool errors       : 0

No private key was requested, read, or stored. No payment was signed.
SpendGuard output is advisory; enforcement belongs to the signing layer.

SpendGuard returned decision: HUMAN_APPROVAL with advisory: true and executionAuthorized: false. The x402 challenge decoded to x402Version: 2, scheme: exact, network: eip155:8453, amount: "250000" (0.25 USDC). Nothing was signed and nothing was paid.

Notes and observations

• Upstream flakiness on the free preview. During testing on 2026-09-19 POST /api/token-preview returned HTTP 503 ({"error":"Market data is temporarily unavailable..."}) intermittently — roughly one call in three — while /api/spendguard/evaluate and /api/token-risk stayed healthy. src/retry.mjs retries only that transient signal, bounded; a genuine failure is still surfaced as an error. Flagging in case the market-data dependency needs a look.

• evaluateSpend validates progressively, revealing required fields one at a time. The accepted shape is { agentId, requestId, amount, chain: 'base', asset: 'USDC', recipient, service?, policy }, where policy requires maxPerTransaction, remainingDailyBudget, requireHumanAbove, maxRepeats, allowedRecipients, and blockUnknownRecipients.

• Reproducibility. A clean clone plus npm install is enough: npm test proves the tool layer offline, npm run agent proves the model-directed path against a live endpoint.

Sanitization

The repository contains only public data: the well-known USDC contract address on Base, the SDK's own published payTo address from the x402 challenge, and BaseScan-visible values. The API key for the model endpoint is supplied at runtime via OPENAI_API_KEY and is not committed, logged, or printed. No private key, seed phrase, personal wallet address, or personal data appears anywhere in this repository.

License

Apache-2.0, matching the upstream SDK.