Hermes Plant MCP Server

Runnable MCP server and integration examples for Hermes Plant, the Agent Commerce Assurance layer that lets AI agents preflight, approve, and prove consequential actions. Start with a one-cent action-safety check, route only high-risk actions into signed review evidence, and pay per call over x402.

What's here: a runnable stdio MCP bridge for registry crawlers and local clients, plus drop-in examples in curl, TypeScript, Python, CrewAI, LangChain, and MCP client configs for Claude Desktop / Cline / Cursor.

Install the Action Safety skill

Install the public, fail-closed Action Safety skill for Codex, Claude Code, Cursor, and other Agent Skills-compatible clients:

npx skills@1.5.18 add JesseGdotIO/hermesplant-mcp-server --skill protect-agent-action

The skill calls the one-cent quick gate before an exact consequential action, binds the result to that unchanged action, and escalates high or critical risk only when the additional $0.25 is authorized. Review triage is never treated as human approval and the skill never expands the caller's permissions.

Source: skills/protect-agent-action · Install guide and trust boundary

Use the hosted MCP connector

For the complete production tool surface, use the canonical Hermes Plant — Agent Commerce Assurance connector on Glama. It exposes Action Safety, Spend Assurance, signed evidence, payment-policy checks, and the component x402 tools through the live Streamable HTTP endpoint.

This repository is the portable, no-secret discovery bridge. It lets registry crawlers and local clients inspect the live catalog and payment contracts without signing a wallet message or spending funds. The hosted connector is the buyer-facing path for invoking the production tools.

Glama registry

This repo is arranged for Glama to build and inspect the MCP server without secrets or funded wallets:

• glama.json declares the GitHub maintainer.
• The root Dockerfile starts the stdio MCP server in mcp-server/.
• npm run smoke:mcp lists all local MCP tools and fetches the live x402 manifest.
• GitHub Actions validates the MCP server, Docker image, shell examples, and no-spend TypeScript/Python client contracts with their real dependencies.

A Glama release is still an account-side action, not a GitHub release. After claiming the server in Glama, use the Dockerfile admin page to deploy the build, wait for the build test to pass, then publish a Glama release version. That release unlocks Glama's Server Coherence and Tool Definition Quality scoring.

Complementary MCP servers

Hermes Plant governs consequential actions and payments; these independent servers cover adjacent layers of an agent stack:

• SINT Protocol — capability authorization and policy enforcement before execution.
• AgentPay MCP — non-custodial wallet execution with spend limits and approval queues.
• Agent Security Scanner MCP — repository, package, prompt, and skill security scanning.

These links describe functional complementarity, not partnerships or endorsements.

Start with an assurance workflow

Workflow	Use it for	Tracked entrypoint
Action Safety	Preflight shell, Git, SQL, deploy, x402, and MCP actions; escalate high-risk work into review plus a signed receipt.	Open workflow
Spend Assurance	Check payment policy, wallet context, and evidence before an agent spends.	Open workflow
Investment Evidence	Run deterministic underwriting and return verifiable evidence in one paid call.	Open workflow

Use the free API key for up to 250 calls/month, the $29/month Agent API Pass for regular volume, or per-call USDC on Base. Public proof and machine-readable contracts are available at hermesplant.com/proof and hermesplant.com/openapi.json.

Component catalog

Nineteen hosted x402 endpoints remain available as composable utilities:

Endpoint	Use it for	Hosted path
DealAnalyzer	DCF, IRR, XIRR, NPV	/agent-services/dealanalyzer
Waterfall	LP/GP private-equity distribution waterfalls	/agent-services/waterfall
Options	Black-Scholes pricing + Greeks	/agent-services/options
Bond	Yield, duration, convexity	/agent-services/bond
CashflowLens	Cash-flow projection + sensitivity	/agent-services/cashflowlens
PortfolioGuard	Portfolio risk scoring	/agent-services/portfolioguard
WalletGuard	Wallet AML + sanctions screening	/agent-services/walletguard
EmailGuard	Email reputation + risk	/agent-services/emailguard
DestructGuard	Block destructive AI-agent commands	/agent-services/destructguard
MCP risk	Score MCP server risk before connecting	/agent-services/mcp-risk
Evidence	Evidence bundle for paid calls	/agent-services/evidence
Payment policy	Inspect/score an x402 payment policy	/agent-services/payment-policy
ReviewQueue	Human-in-the-loop approval routing	/agent-services/reviewqueue

Agents discover endpoints through OpenAPI, llms.txt, the x402 manifest, the API catalog, MCP metadata, or agent skills. The workflow links above carry source-specific attribution so registry traffic can be evaluated against paid calls instead of impressions.

How an x402 call works

Client                    Hermes Plant                 Facilitator
  |                            |                            |
  | POST /endpoint             |                            |
  |--------------------------->|                            |
  | 402 Payment Required       |                            |
  | + PAYMENT-REQUIRED         |                            |
  |<---------------------------|                            |
  | sign payment locally       |                            |
  | POST /endpoint             |                            |
  | + PAYMENT-SIGNATURE        |                            |
  |--------------------------->| verify signature           |
  |                            |--------------------------->|
  |                            | ok                         |
  |                            |<---------------------------|
  | 200 OK + result            | settle payment             |
  |<---------------------------|--------------------------->|

1. Client makes an HTTP request.
2. Server replies with 402 Payment Required plus a PAYMENT-REQUIRED header carrying the price, network, asset, recipient, and timeout.
3. Client parses the challenge, signs a USDC transfer authorization locally, and replays the request with a PAYMENT-SIGNATURE header.
4. Server verifies the signature via the facilitator, runs the work, settles the payment on-chain, and returns 200 OK with the result plus a PAYMENT-RESPONSE header.

The full spec lives at github.com/x402-foundation/x402.

Discovery surfaces

These let any agent or human self-onboard without help:

• hermesplant.com/llms.txt - agent-readable catalog
• hermesplant.com/openapi.json - full OpenAPI 3.1
• hermesplant.com/.well-known/x402 - x402 manifest with facilitator, network, asset, prices, and payTo metadata
• hermesplant.com/.well-known/api-catalog - RFC 9727-style API catalog
• hermesplant.com/.well-known/mcp/server-card.json - MCP server descriptor
• hermesplant.com/mcp - Streamable HTTP MCP endpoint

MCP tools in this repo

The runnable stdio server exposes five read-only discovery tools:

Tool	Purpose
hermesplant_x402_manifest	Fetch the live x402 manifest before paid calls.
hermesplant_llms_catalog	Fetch the agent-readable llms.txt catalog.
hermesplant_api_catalog	Fetch the machine-readable API catalog.
hermesplant_mcp_server_card	Fetch the hosted MCP server descriptor.
hermesplant_list_hosted_tools	Introspect the hosted Streamable HTTP MCP endpoint and list its advertised tools.

These local tools do not sign wallet messages, approve transactions, call paid endpoints, or spend USDC. They expose the discovery layer that clients need before invoking paid hosted tools.

Quickstart

Pick the runtime that matches your stack:

Runtime	Folder	Notes
curl / Bash	curl/	Pure shell; useful for inspecting the 402 handshake
TypeScript	typescript/	Uses @x402/fetch + @modelcontextprotocol/sdk
Python	python/	Uses the x402 package
CrewAI	crewai/	Finance-agent crew calling Hermes endpoints
LangChain	langchain/	LangChain Tool wrapping Hermes
MCP config	mcp-config/	One-paste config for Claude Desktop / Cline / Cursor
MCP server	mcp-server/	Runnable stdio MCP bridge for discovery, server-card inspection, and hosted-tool listing

Run the MCP server locally

npm install
npm run smoke:mcp
npm start

MCP server registry build

This repo includes a root glama.json and root Dockerfile for MCP registry crawlers:

docker build -t hermesplant-mcp-server .
docker run --rm -i hermesplant-mcp-server

The container starts the stdio MCP bridge in mcp-server/, which exposes Hermes Plant discovery tools and hosted MCP metadata without requiring API keys.

Wallet setup

The guarded paid-call examples require:

• A funded wallet on Base mainnet with chain id 8453.
• Enough USDC for the selected endpoint and a small amount of ETH for gas.
• EVM_PRIVATE_KEY plus the explicit opt-in HERMES_ALLOW_PAYMENT=1.

The included CashflowLens clients cap payment requirements at $0.20 USDC and register only Base mainnet. Leave the opt-in unset for imports and tests. Never commit a private key. These production examples do not claim testnet support; use an x402 test resource server for testnet integration work.

Status

These examples target the production deployment at hermesplant.com. Endpoint signatures may evolve, so cross-reference openapi.json and the /.well-known/x402 manifest before going to production.

Contributing

Issues and PRs welcome. New runtime? New framework? Open a PR with one working example and a tight README.

License

MIT - see LICENSE.