JustHandled Agent Utility Gateway MCP server
✓ VerifiedProvides thirty-two guarded agent utilities and maintained-data lookups via USDC payments on the Base network.
Also known as justhandledlabs/justhandled-agent-client, justhandled-agent-client, @justhandledlabs/agent-client
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 1,509
- Latest version
- 0.11.1
- Last commit
- Aug 2, 2026
- License
- MIT
What is JustHandled Agent Utility Gateway MCP?
JustHandled Agent Utility Gateway provides thirty-two guarded agent utilities and maintained-data lookups via USDC payments on the Base network.
Summary generated from the project's README
About JustHandled Agent Utility Gateway MCP server
JustHandled Agent Utility Gateway provides a local MCP server that gives developers access to thirty-two guarded utilities and data lookups. The server functions by connecting to a pinned gateway via a JavaScript client, requiring a dedicated low-balance Base wallet provided through a private key environment variable. It is designed for users who need verified evidence products or maintained-data snapshots, such as the Chicago Contract Change Packet.
Users interact with the server through a catalog tool and individual paid tools for each gateway utility. The system uses a strict security model where the price, chain, asset, and receiver are pinned in the code to prevent unauthorized spending. Every paid request, which costs either $0.05 or $0.25 USDC on the Base network, begins with an unpaid preview to validate terms. This ensures that the client fails closed if any payment terms do not match the expected values before a signature is ever requested.
What you can do with it
- 1Verify file portabilityAn AI client can run a preflight check to ensure specific file paths meet portability requirements.
- 2Retrieve contract change dataA developer can request the live Chicago Contract Change Packet for maintained data lookups.
- 3Audit channel experiment resultsAn agent can access a postmortem report regarding a specific channel experiment.
- 4Check API contract driftA developer can use the catalog to find products that detect drift in API responses.
Written from the project's README. Every use case is checked against a quote from it.
How to install JustHandled Agent Utility Gateway MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall JustHandled Agent Utility Gateway MCP in Claude Code
$ claude mcp add --env 'JH_EVM_PRIVATE_KEY=<YOUR_JH_EVM_PRIVATE_KEY>' justhandled-agent-client -- npx -y @justhandledlabs/agent-clientInstall JustHandled Agent Utility Gateway MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"justhandled-agent-client": {
"command": "npx",
"args": [
"-y",
"@justhandledlabs/agent-client"
],
"env": {
"JH_EVM_PRIVATE_KEY": "<YOUR_JH_EVM_PRIVATE_KEY>"
}
}
}
}Install JustHandled Agent Utility Gateway MCP in VS Code
.vscode/mcp.json
{
"servers": {
"justhandled-agent-client": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@justhandledlabs/agent-client"
],
"env": {
"JH_EVM_PRIVATE_KEY": "<YOUR_JH_EVM_PRIVATE_KEY>"
}
}
}
}Install JustHandled Agent Utility Gateway MCP in VS Code CLI
$ code --add-mcp '{"name":"justhandled-agent-client","type":"stdio","command":"npx","args":["-y","@justhandledlabs/agent-client"],"env":{"JH_EVM_PRIVATE_KEY":"<YOUR_JH_EVM_PRIVATE_KEY>"}}'Install JustHandled Agent Utility Gateway MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"justhandled-agent-client": {
"command": "npx",
"args": [
"-y",
"@justhandledlabs/agent-client"
],
"env": {
"JH_EVM_PRIVATE_KEY": "<YOUR_JH_EVM_PRIVATE_KEY>"
}
}
}
}Install JustHandled Agent Utility Gateway MCP in Codex
$ codex mcp add justhandled-agent-client --env 'JH_EVM_PRIVATE_KEY=<YOUR_JH_EVM_PRIVATE_KEY>' -- npx -y @justhandledlabs/agent-clientInstall JustHandled Agent Utility Gateway MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.justhandled-agent-client] command = "npx" args = ["-y", "@justhandledlabs/agent-client"] [mcp_servers.justhandled-agent-client.env] JH_EVM_PRIVATE_KEY = "<YOUR_JH_EVM_PRIVATE_KEY>"
Install JustHandled Agent Utility Gateway MCP in Gemini CLI
$ gemini mcp add -s user -e 'JH_EVM_PRIVATE_KEY=<YOUR_JH_EVM_PRIVATE_KEY>' justhandled-agent-client npx -- -y @justhandledlabs/agent-clientInstall JustHandled Agent Utility Gateway MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"justhandled-agent-client": {
"command": "npx",
"args": [
"-y",
"@justhandledlabs/agent-client"
],
"env": {
"JH_EVM_PRIVATE_KEY": "<YOUR_JH_EVM_PRIVATE_KEY>"
}
}
}
}Configuration
JH_EVM_PRIVATE_KEYRequiredSecretPrivate key for a dedicated Base wallet funded with USDC. Never use a primary wallet.
| Name | Description | |
|---|---|---|
| JH_EVM_PRIVATE_KEY | Private key for a dedicated Base wallet funded with USDC. Never use a primary wallet. | RequiredSecret |
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablejusthandledlabs/justhandled-agent-client is public and reachablegithub.com/justhandledlabs/justhandled-agent-client ↗Pass
- Package names this repository as its source@justhandledlabs/agent-client names justhandledlabs/justhandled-agent-client as sourcenpmjs.com/package/@justhandledlabs/agent-client ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @justhandledlabs/agent-clientnpmjs.com/package/@justhandledlabs/agent-client/v/0.11.1#pro ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-02github.com/justhandledlabs/justhandled-agent-client ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @justhandledlabs/agent-clientPass
- No critical advisory in the package or its dependencies117 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubJustHandled Agent Client
A guarded CLI, JavaScript client, and local MCP server for the JustHandled Agent Utility Gateway. The package exposes thirty-two preflights, maintained-data lookups, and evidence products. Twenty-two products cost $0.05 USDC; ten evidence-heavy or maintained-data products cost $0.25, including the live Chicago Contract Change Packet. Every paid call returns a versioned evidence receipt.
The client fails closed before signing. It accepts only the pinned JustHandled gateway, Base mainnet, canonical Base USDC, the exact per-product price, and the published merchant receiver. Customer inputs and complete customer results are not persisted by the gateway; maintained public-source snapshots are labeled in the receipt.
Inspect without a wallet
npx --package @justhandledlabs/agent-client justhandled-agent catalog
npx --package @justhandledlabs/agent-client justhandled-agent preview filename-portability-preflight --json '{"paths":["CON.txt"]}'
npx --package @justhandledlabs/agent-client justhandled-agent preview agent-run-evidence-pack --file agent-run-evidence-pack.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview agent-distribution-readiness-pack --file agent-distribution-readiness-pack.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview community-rule-credibility-preflight --file community-rule-credibility-preflight.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview qualified-demand-ledger --file qualified-demand-ledger.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview channel-fit-evidence-matrix --file channel-fit-evidence-matrix.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview proof-to-channel-evidence-packet --file proof-to-channel-evidence-packet.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview channel-experiment-postmortem --file channel-experiment-postmortem.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview chicago-contract-change-packet --file chicago-contract-change-packet.sample.json
Preview performs an unpaid request and validates the returned x402 terms. It does not sign or spend.
The catalog includes API-response contract drift, webhook contract and replay, and policy-change evidence products. Packaged example inputs are available in examples/.
Machine-readable products, exact payment terms, and free deterministic fixtures are available from the gateway's product catalog, OpenAPI document, and sandbox index.
Execute one paid utility
Use a dedicated low-balance Base wallet. Never provide a primary wallet key.
export JH_EVM_PRIVATE_KEY=0x...
npx --package @justhandledlabs/agent-client justhandled-agent call filename-portability-preflight --json '{"paths":["CON.txt"]}'
PowerShell:
$env:JH_EVM_PRIVATE_KEY = "0x..."
npx.cmd --package @justhandledlabs/agent-client justhandled-agent call filename-portability-preflight --json '{"paths":["CON.txt"]}'
MCP configuration
{
"mcpServers": {
"justhandled": {
"command": "npx",
"args": ["-y", "@justhandledlabs/agent-client"],
"env": {
"JH_EVM_PRIVATE_KEY": "0xDEDICATED_LOW_BALANCE_WALLET_KEY"
}
}
}
}
The MCP server exposes a free catalog tool plus one paid tool per gateway utility. Missing wallet configuration produces an error instead of a payment attempt.
The package declares the official MCP Registry identity io.github.justhandledlabs/agent-gateway. Registry identity is discovery metadata only: installing or listing the server does not spend funds, and paid execution still requires a dedicated wallet plus the client's exact-term checks.
Security model
- Price, chain, asset, receiver, and gateway origin are pinned in code.
- The ten $0.25 products' 250,000-base-unit price is pinned separately from 50,000-base-unit checks.
- Every execution starts with an unpaid 402 preview.
- A mismatched term aborts before signing.
- The package never prints the private key.
- The gateway does not persist customer inputs or complete customer results. Maintained-data products may retain normalized public-source snapshots and disclose that state in the receipt.
- Treat all crypto transfers as irreversible and fund only a dedicated wallet.
Development
npm install
npm run check
The gateway implementation is intentionally not included in this client repository.
JustHandled Agent Utility Gateway MCP questions
How do I add JustHandled Agent Utility Gateway MCP to Claude Code?
Run claude mcp add --env 'JH_EVM_PRIVATE_KEY=<YOUR_JH_EVM_PRIVATE_KEY>' justhandled-agent-client -- npx -y @justhandledlabs/agent-client in your terminal. Add --scope user to make it available in every project.
How do I add JustHandled Agent Utility Gateway MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How much do the utilities cost?
Twenty-two products cost $0.05 USDC, while ten evidence-heavy or maintained-data products cost $0.25.
Can I inspect the utilities without a wallet?
Yes, you can use the preview command to perform an unpaid request and validate terms without signing or spending.
Does the gateway store my customer data?
No, the gateway does not persist customer inputs or complete customer results.
What happens if I don't configure a wallet for the MCP server?
The server will produce an error instead of attempting a payment.