Skip to main content
Glama

NeedRail

CI License Python 3.11+ MCP

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.

Option

Amount

Link

Public Goods Support

$25

Donate

Monthly Sponsor

$25/mo

Sponsor

Kernel Support

$99

Donate

Agent rail: x402-cloudflare-starter

Surfaces

Surface

Entry

MCP (stdio)

python -m needrail.mcp_server

CLI

needrail-cli status

API

needrail

SDK

from needrail.sdk import NeedRailClient

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_server

License

Apache-2.0

Available Tools

10 tools
claim_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

    A4.5/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      MCP 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.
      30
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the x402 protocol that lets AI agents discover and call payment-gated HTTP APIs automatically.
      Apache 2.0