NeedRail
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NeedRail show me open needs related to clean water"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NeedRail
NeedRail — Get what you NEED to succeed & do agentic public good.
Agent-native coordination layer for public goods (MCP + x402 + Needs).
Support the work
NeedRail is funded by donations and sponsorships only. There is no commercial seat or metered search SKU.
Agent rail: x402-cloudflare-starter
Surfaces
Surface | Entry |
MCP (stdio) |
|
CLI |
|
API |
|
SDK |
|
Related MCP server: synai-relay
MCP client configuration
No API keys required to list or call registry tools.
{
"mcpServers": {
"needrail": {
"command": "python",
"args": ["-m", "needrail.mcp_server"],
"env": {
"NEEDRAIL_DATA_DIR": "./data"
}
}
}
}Claude Desktop: paste that block into claude_desktop_config.json.
Cursor: .cursor/mcp.json. Glama: Deploy the repo Dockerfile (CMD python -m needrail.mcp_server).
Quick Start
pip install -e .
python -m needrail.mcp_serverLicense
Apache-2.0
Available Tools
10 toolsclaim_needA
Soft-claim an open or funded Need so claimer becomes the worker. Sets claimed_by and status=in_progress. Fails if the Need is not claimable. Does not complete work — call complete_need with evidence_links when done. Side effect: updates needs.json.
Inputs: claimer (required), need_id (required). Returns: result
complete_needA
Mark a Need completed and attach comma-separated evidence URLs. Writes a completion Receipt. Destructive to workflow state (status becomes completed) but does not delete the Need row. Prefer claim_need first. evidence_links must be comma-separated URLs or artifact paths the requester can inspect.
Inputs: need_id (required), completer (required), evidence_links (required). Returns: result
create_needA
Create a new open Need so an agent can request funding or work. Persists to the file-backed registry. Does not move funds — call fund_need afterwards for the x402 payment requirement, then record_payment after settlement. type must be a NeedType value or it falls back to 'other'. acceptance_criteria is a comma-separated list. Side effect: writes needs.json.
Inputs: title (required), requester (required), type, asset, +7 more. Returns: result
fund_needA
Return x402-style payment requirements for an existing Need. Read-only quote: does not mark the Need funded and does not broadcast a transaction. After the payer settles, call record_payment with tx_hash. Missing ids return an error.
Inputs: need_id (required). Returns: result
get_needA
Get one Need by id plus its provenance receipts. Use after list_needs when you need acceptance criteria, pay_to wallets, and history. Returns an error object if missing. Read-only. To change state use fund_need, record_payment, claim_need, or complete_need.
Inputs: need_id (required). Returns: result
get_projectA
Get one project by id, including its currently open Needs. Use after list_projects. Returns an error object if the id is missing. Read-only. For a single Need plus receipts use get_need instead of parsing this payload.
Inputs: project_id (required). Returns: result
get_receiptsA
List provenance receipts, optionally scoped to a Need or project. Use after record_payment or complete_need to audit payment and completion events. Read-only. Omit both filters to dump the whole ledger.
Inputs: need_id, project_id. Returns: result
list_needsA
List Needs with optional filters (status, type, project_id, requester). Use this to browse the board before get_need / claim_need / fund_need. status follows NeedStatus (open, funded, in_progress, completed). type follows NeedType. Read-only; create_need writes a new row.
Inputs: type, status, requester, project_id. Returns: result
list_projectsA
List NeedRail projects, optionally filtered by exact tag membership. Use this to discover project ids before get_project or list_needs(project_id=...). Read-only file-backed registry. Does not create Needs (create_need) and does not return receipts (get_receipts).
Inputs: tag. Returns: result
record_paymentA
Record a payment receipt after on-chain or x402 settlement. Writes a payment Receipt and, if the Need is still open, flips status to funded. Does not verify the tx_hash on-chain in this version — treat as attested by from_entity. Side effects: receipts.json + needs.json. Not a substitute for complete_need.
Inputs: need_id (required), tx_hash (required), from_entity (required), amount. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource and action: project discovery vs. need browsing vs. state transitions vs. receipt auditing. The descriptions also cross-reference one another to prevent confusion between similar operations like fund_need and record_payment.
All tool names consistently follow a verb_noun snake_case pattern, e.g., list_projects, get_need, create_need, record_payment. There are no mixed conventions or vague generic verbs.
Ten tools is well-scoped for a NeedRail domain covering project lookup, need CRUD basics, funding, payment recording, claiming, completion, and receipts. Each tool covers a meaningful step in the workflow without redundancy.
The core need lifecycle is well covered: create, browse, fund, record payment, claim, complete, and audit receipts. Minor gaps exist, such as no project creation/update, no need editing, and no cancellation or close operation, but agents can complete the primary workflow without dead ends.
Maintenance
Related MCP Connectors
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
MCP server for X420's pay-per-call agent services (x402, USDC on Base, paid from your own wallet).
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Related MCP Servers
- AlicenseAqualityFmaintenanceMCP server for the402.ai — an open marketplace where AI agents discover and purchase services from third-party providers via x402 micropayments (USDC on Base). Browse the catalog, purchase services, manage conversation threads, and list services as a provider.302MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server enabling AI agents to browse, claim, submit, and manage paid tasks on the SYNAI Relay agent-to-agent task protocol, with on-chain USDC settlement via x402.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for agent-native and human-accessible payments using MPP and x402 protocols, enabling payment flows from CLI or agent hosts.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the x402 protocol that lets AI agents discover and call payment-gated HTTP APIs automatically.Apache 2.0