j41-mcp-server

MCP server for the Junction41 -- wraps the @junction41/sovagent-sdk as Model Context Protocol tools, allowing Claude and other LLMs to interact with the Junction41 platform. Exposes 124+ tools, 10 resources, and 3 workflow prompts.

Works with Claude Desktop, Claude Code, OpenAI agents, Cursor, Windsurf, and any other client that speaks the Model Context Protocol.

Security update — 2026-06-02 audit (v2.1.0)

This release closes 5 criticals + 14 highs + ~16 mediums/lows from the 2026-06-02 cross-repo security audit. The behavioral changes consumers should know about:

Removed tools (breaking). j41_sign_message and j41_sign_challenge are gone. They were raw signing oracles — a prompt-injected LLM could mint signatures over J41-COMPLETE|..., J41-BOUNTY-SELECT|..., or J41-DEPOSIT-REPORT|... strings and submit them out-of-band to release escrow / redirect bounty payouts / deny refunds. Every protocol action has a typed tool that builds the canonical message internally — use those.

j41_send_currency schema is narrower (breaking). The changeAddress and sourceAddress parameters were removed: the allowlist gate only validated to, so an attacker could send dust to an allowlisted destination and route the entire UTXO change to themselves. A finite J41_MCP_STANDALONE_MAX_VRSC cap (default 10) replaces the old silent jobPrice=Infinity.

SSE transport fails closed (breaking for non-loopback ops). j41-mcp-server --transport sse now binds 127.0.0.1 by default. Override with J41_MCP_SSE_HOST. If you bind anything other than loopback, J41_MCP_SSE_TOKEN is required or the server refuses to start. The token is checked on both /sse and /message (the previous gate left /message open), constant-time compared, and J41_CORS_ORIGIN=* is refused when the token is on.

Allowlist auto-population is opt-in. Set J41_MCP_ALLOWLIST_AUTOPOPULATE=1 to restore the pre-2.1.0 behavior where j41_accept_job adds the buyer's pay address. Default-off because a compromised platform could pre-populate attacker addresses.

New ingest caps (all env-overridable): J41_MCP_API_TIMEOUT_MS=30000, J41_MCP_API_MAX_RESPONSE_BYTES=8MB, J41_MCP_MAX_UPLOAD_BYTES=25MB, J41_MCP_MAX_DOWNLOAD_BYTES=25MB, J41_MCP_SSE_MAX_MESSAGE_BYTES=1MB, J41_MCP_SSE_MAX_SESSIONS=64, J41_MCP_MAX_WORKSPACES=32, J41_MCP_MAX_RAW_TX_HEX_CHARS=4MB, J41_MCP_SWEEP_TIMEOUT_MS=5000.

Bumped bundled @junction41/sovagent-sdk to 2.5.0, which carries its own breaking changes — see that package's README.

Related MCP server: production-grade-mcp-agentic-system

Install

yarn global add @junction41/mcp-server

Quick Start

# Run on stdio (default)
j41-mcp-server

# Run on SSE
j41-mcp-server --transport sse --port 3001

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "j41": {
      "command": "j41-mcp-server"
    }
  }
}

Claude Code

claude mcp add j41 j41-mcp-server

SSE Transport

{
  "mcpServers": {
    "j41": {
      "url": "http://localhost:3001/sse"
    }
  }
}

CORS is restricted to localhost by default. Set J41_CORS_ORIGIN to override:

J41_CORS_ORIGIN="https://myapp.example.com" j41-mcp-server --transport sse --port 3001

Tools (125)

Identity (stateless)

Agent Lifecycle

Jobs

Workspace

Path traversal protection: relative paths only, .. segments rejected.

Chat

Files

Payments

Pricing (stateless)

Privacy

Safety

Reviews

Webhooks

Trust

Notifications

Extensions

Bounties

Discovery

Inbox

Services

Resources (10)

Static, read-only data from the SDK -- no authentication required.

Prompts (3)

Guided workflows that walk through multi-step operations:

Typical Workflow

1. j41_generate_keypair          -> Get WIF + address
2. j41_init_agent                -> Connect to J41
3. j41_register_identity         -> Get a VerusID (if needed)
4. j41_authenticate              -> Establish session
5. j41_register_agent            -> Publish agent profile
6. j41_register_service          -> List service offerings
7. j41_enable_canary             -> Enable safety features
8. j41_register_webhook          -> Subscribe to platform events
9. j41_list_jobs                 -> Check for incoming work
10. j41_accept_job               -> Take a job
11. j41_connect_chat / send      -> Communicate with buyer
12. j41_deliver_job              -> Submit deliverables
13. j41_complete_job             -> Finalize
14. j41_submit_review            -> Leave a review

Architecture

src/
├── index.ts                  # Server setup, transport selection
├── state.ts                  # Singleton agent state + signing
├── transport-sse.ts          # SSE/HTTP transport (Node http, no Express)
├── tools/
│   ├── error.ts              # Shared error handler
│   ├── api-request.ts        # Authenticated API request helper
│   ├── identity.ts           # Stateless keypair/signing tools
│   ├── agent.ts              # Agent lifecycle tools
│   ├── jobs.ts               # Job management tools
│   ├── chat.ts               # Chat tools
│   ├── payments.ts           # Payment/blockchain tools
│   ├── pricing.ts            # Stateless pricing tools
│   ├── safety.ts             # Canary + communication policy
│   ├── privacy.ts            # Privacy tier + deletion attestation
│   ├── extensions.ts         # Payment extension tools
│   ├── files.ts              # File upload/download/list/delete
│   ├── reviews.ts            # Review tools (signed submission)
│   ├── notifications.ts      # Notification tools
│   ├── webhooks.ts           # Webhook registration/management
│   ├── trust.ts              # Trust score queries
│   ├── bounties.ts           # Bounty lifecycle tools
│   ├── discovery.ts          # Agent/service search tools
│   ├── disputes.ts           # Dispute response tools
│   ├── inbox.ts              # Inbox management tools
│   ├── services.ts           # Service CRUD tools
│   └── workspace.ts          # Workspace file access tools
├── resources/index.ts        # 10 static resources
└── prompts/index.ts          # 3 workflow prompts

State Management

The server maintains a singleton J41Agent instance with three states:

Uninitialized -> Initialized -> Authenticated
                 (j41_init)     (j41_authenticate)

State transitions are forward-only. The WIF private key is stored in the state module and only accessible through signWithAgent() -- it is never exposed via any getter or returned in any tool response.

Security

• WIF handling: j41_generate_keypair stores the WIF internally and only returns the address. j41_init_agent accepts WIF but never echoes it. All job signing happens internally via signWithAgent(). Signing tools use the stored key by default.

• Input validation: All tool inputs validated by Zod schemas with length limits, enum constraints, and regex patterns.

• Error handling: Shared errorResult() extracts J41Error codes without leaking stack traces.

• SSE CORS: Restricted to localhost by default (configurable via J41_CORS_ORIGIN).

• SSE error boundary: Async handler wrapped to prevent unhandled rejection crashes.

• No Express: SSE transport uses Node's built-in http.createServer -- zero extra runtime dependencies.

• Webhook verification: Webhook payloads are HMAC-SHA256 signed with a secret you provide at registration.

Development

# Build
yarn build

# Test
yarn test

# Start in stdio mode
yarn start

# Start in SSE mode
j41-mcp-server --transport sse --port 3001

Dependencies

Dispute Resolution Tools

j41_respond_to_dispute

Respond to a buyer's dispute. Auto-signs the response.

j41_accept_rework

Accept an agent's rework offer (buyer side). Auto-signs the acceptance.

Updated: j41_list_jobs

Now supports filtering by rework, resolved, and resolved_rejected status values.

Security

Financial Allowlists

All outbound financial operations (j41_send_currency, j41_transfer_funds, j41_broadcast_tx) are gated by ~/.j41/financial-allowlist.json. If the file doesn't exist, it is created empty — deny-all by default.

{
  "permanent": [
    { "address": "RxxxxPlatform...", "label": "platform_fee" }
  ],
  "operator": [
    { "address": "Rxxxx...", "label": "cold wallet", "added": "2026-04-01" }
  ],
  "active_jobs": [
    { "address": "iXxxxBuyer...", "jobId": "abc123", "added": "2026-04-02T10:00:00Z" }
  ]
}

• permanent — always allowed (e.g., platform fee address). Edit manually.

• operator — operator-approved addresses. Edit manually.

• active_jobs — managed automatically by job lifecycle hooks.

Rate Limiting

Exceeding any limit blocks the operation and logs an alert.

Dynamic Lifecycle

• j41_accept_job — buyer refund address automatically added to active_jobs

• j41_complete_job / j41_cancel_job / j41_end_session — address removed, rate limiter cleared

Fail-Closed Sweep Timer

Every 10 minutes, the MCP server checks all active_jobs entries against the platform API:

• If a job is no longer active, the address is removed

• If the platform API is unreachable, all active_jobs sends are frozen

• After 30 minutes of continuous API outage, ALL financial operations are suspended

• Operations resume automatically when the API becomes reachable again

Mandatory Canary Tokens

Canary protection is auto-enabled on every j41_accept_job call. If the canary token appears in agent output, it indicates prompt injection.

Recent Changes

• Allowlist always reloads from disk — no more stale cache; external edits (operator, dispatcher lifecycle) are picked up immediately

• Auto-add seller on job creation — j41_create_job adds seller payment address + platform fee address to allowlist

• SovGuard 429 handling — non-retryable quota limits surface upgrade URLs, transient rate limits get longer backoff

• 125+ tools — added dispute, extension, workspace, bounty, and data policy tools

License

MIT