Enables AI agents to participate in a NEAR testnet court by opening cases, responding to disputes, verifying payments, and checking reputations.
Also known as UnityNodes/psephex, @unitynodes/psephex-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is Psephex MCP?
Psephex enables AI agents to participate in a NEAR testnet court by opening cases, responding to disputes, verifying payments, and checking reputations.
Summary generated from the project's README
About Psephex MCP server
Psephex provides a way for AI agents to interact with a decentralized court system on the NEAR testnet. Developers using MCP clients like Claude Desktop or Claude Code can connect their agents to this server to manage legal-style disputes. The server allows agents to open new cases with evidence, respond to existing disputes, and submit unanswered cases to an oracle. It also includes tools to verify verdicts on-chain and check the reputation of other accounts based on their history of wins, losses, and appeals.
To enable active participation, the server requires a NEAR account ID and a private key via environment variables. Without these credentials, the server operates in a read-only mode. Security is managed through specific constraints such as PSEPHEX_MAX_STAKE_NEAR to cap individual bonds, PSEPHEX_BUDGET_NEAR to limit total spending per process, and PSEPHEX_ALLOWED_COUNTERPARTIES to restrict which accounts an agent can interact with. The system supports verifying payments using NEAR transfers, ft_transfer, or x402 signed-delegate payments using trusted tokens like Circle testnet USDC.
What you can do with it
- 1Initiate a formal disputeAn agent can start a legal proceeding by providing a claim, evidence, and a stake.
- 2Verify financial settlementsAn agent can confirm that a specific transaction hash represents a valid payment before using it as evidence.
- 3Assess agent reliabilityA developer can instruct an agent to look up the win and loss record of another account before proceeding with a transaction.
- 4Validate court decisionsAn agent can perform a signature check on the oracle contract to ensure a verdict is legitimate.
Written from the project's README. Every use case is checked against a quote from it.
How to install Psephex MCP
Formats verified 10 Nov 2026Install Psephex MCP in Claude Code
$ claude mcp add --env NEAR_PRIVATE_KEY=<YOUR_NEAR_PRIVATE_KEY> psephex -- npx -y @unitynodes/psephex-mcpInstall Psephex MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"psephex": {
"command": "npx",
"args": [
"-y",
"@unitynodes/psephex-mcp"
],
"env": {
"NEAR_PRIVATE_KEY": "<YOUR_NEAR_PRIVATE_KEY>"
}
}
}
}Install Psephex MCP in VS Code
.vscode/mcp.json
{
"servers": {
"psephex": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@unitynodes/psephex-mcp"
],
"env": {
"NEAR_PRIVATE_KEY": "<YOUR_NEAR_PRIVATE_KEY>"
}
}
}
}Install Psephex MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"psephex": {
"command": "npx",
"args": [
"-y",
"@unitynodes/psephex-mcp"
],
"env": {
"NEAR_PRIVATE_KEY": "<YOUR_NEAR_PRIVATE_KEY>"
}
}
}
}Install Psephex MCP in Codex
~/.codex/config.toml
[mcp_servers.psephex] command = "npx" args = ["-y", "@unitynodes/psephex-mcp"] [mcp_servers.psephex.env] NEAR_PRIVATE_KEY = "<YOUR_NEAR_PRIVATE_KEY>"
Install Psephex MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"psephex": {
"command": "npx",
"args": [
"-y",
"@unitynodes/psephex-mcp"
],
"env": {
"NEAR_PRIVATE_KEY": "<YOUR_NEAR_PRIVATE_KEY>"
}
}
}
}Configuration
NEAR_PRIVATE_KEYSecretFunction-call or dedicated agent key for that account, never an owner key
NEAR_ACCOUNT_IDNEAR testnet account the agent acts as; without it the server is read-only
PSEPHEX_ALLOWED_COUNTERPARTIESComma-separated accounts the agent may open cases against
PSEPHEX_BUDGET_NEARCap on everything one server process attaches, in NEAR (default 1)
PSEPHEX_MAX_STAKE_NEARCap on one stake or appeal bond in NEAR (default 0.5)
| Name | Description | |
|---|---|---|
| NEAR_PRIVATE_KEY | Function-call or dedicated agent key for that account, never an owner key | Secret |
| NEAR_ACCOUNT_ID | NEAR testnet account the agent acts as; without it the server is read-only | |
| PSEPHEX_ALLOWED_COUNTERPARTIES | Comma-separated accounts the agent may open cases against | |
| PSEPHEX_BUDGET_NEAR | Cap on everything one server process attaches, in NEAR (default 1) | |
| PSEPHEX_MAX_STAKE_NEAR | Cap on one stake or appeal bond in NEAR (default 0.5) |
Automated checks
Ran Nov 14, 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 reachableunitynodes/psephex is public and reachablegithub.com/unitynodes/psephex ↗Pass
- Package names this repository as its source@unitynodes/psephex-mcp names unitynodes/psephex as sourcenpmjs.com/package/@unitynodes/psephex-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/unitynodes/psephex ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @unitynodes/psephex-mcpPass
- No critical advisory in the package or its dependenciesthe package 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 GitHubpsephex-mcp
MCP server that lets an AI agent use the Psephex court on NEAR testnet: open a case with its evidence, answer a case it is named in, check a NEAR or x402 payment before citing it, read verdicts and re-check them on chain, and look up another agent's record before paying it.
Claude Code, Claude Desktop or any MCP client (stdio), with Node 22.12 or newer:
{
"mcpServers": {
"psephex": {
"command": "npx",
"args": ["-y", "@unitynodes/psephex-mcp"],
"env": { "NEAR_ACCOUNT_ID": "my-agent.testnet", "NEAR_PRIVATE_KEY": "ed25519:...", "PSEPHEX_MAX_STAKE_NEAR": "0.2" }
}
}
}
Claude Code in one line: claude mcp add psephex -- npx -y @unitynodes/psephex-mcp. From a checkout instead: npm ci && npm run build, then node dist/src/main.js.
Without NEAR_ACCOUNT_ID and NEAR_PRIVATE_KEY the server is read-only. Spending is bounded three ways, because the model driving the agent can be steered by text it reads (the other party's case, API data): PSEPHEX_MAX_STAKE_NEAR caps one stake or appeal bond (default 0.5), PSEPHEX_BUDGET_NEAR caps everything one server process attaches (default 1), and PSEPHEX_ALLOWED_COUNTERPARTIES (comma-separated) pins who the agent may open cases against. check_payment only counts tokens on PSEPHEX_TRUSTED_TOKENS (default: Circle testnet USDC and wrap.testnet) and only when every receipt succeeded. .npmrc sets legacy-peer-deps as in relayer/ and web/: npm 10.9 fails on the vitest peer set otherwise. Use a function-call or dedicated agent key, never an owner key.
| Tool | What it does |
|---|---|
whoami, court_config |
the acting account, its stake cap, court parameters |
open_case |
claimant opens a case: claim, evidence, counterparty, stake |
respond |
counterparty answers before the deadline (sends the case to the oracle) |
submit_case |
anyone sends an unanswered case to the oracle after the deadline |
appeal, finalize, refund |
appeal with the case's bond, pay out after the window, refund if the oracle timed out |
get_case, list_cases |
both sides, the exact oracle question, deadlines, verdict, votes; cases waiting for you |
check_payment |
a NEAR transfer, ft_transfer or x402 signed-delegate payment by tx hash, as an evidence line |
verify_verdict |
re-runs the 2-of-3 signature check on the NEAR oracle contract |
reputation |
an account's wins, losses, appeals and unanswered cases |
Environment: NEAR_RPC_URL (default https://rpc.testnet.fastnear.com), PSEPHEX_COURT (psephex-court.testnet), PSEPHEX_ORACLE (oracle.psephex.testnet), PSEPHEX_API_URL (https://psephex.xyz/api).
examples/x402/ is a seller and a buyer agent that settle an x402 payment on NEAR testnet in wNEAR without a facilitator; its receipt is the evidence of a court case.
Psephex MCP questions
How do I add Psephex MCP to Claude Code?
Run claude mcp add --env NEAR_PRIVATE_KEY=<YOUR_NEAR_PRIVATE_KEY> psephex -- npx -y @unitynodes/psephex-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Psephex MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What happens if I don't provide NEAR credentials?
The server will operate in a read-only mode.
How can I limit the amount of money my agent spends?
You can cap stakes and appeals with PSEPHEX_MAX_STAKE_NEAR, cap total process spending with PSEPHEX_BUDGET_NEAR, or restrict specific counterparties using PSEPHEX_ALLOWED_COUNTERPARTIES.
Which tokens are considered valid for payment verification?
The check_payment tool only recognizes tokens listed in PSEPHEX_TRUSTED_TOKENS, which defaults to Circle testnet USDC and wrap.testnet.