# REALJOIN MCP Server

REALJOIN provides a zero-dependency local stdio MCP server for service discovery, public pricing, quote and order previews, checkout previews, and order status checks.

## Install

Install the release archive with Node.js 20 or newer:

```bash
npm install -g https://www.realjoin.io/realjoin-agent-kit-1.0.0.tgz
```

Checksums: https://www.realjoin.io/realjoin-agent-checksums.txt

Standalone scripts are also available:

- CLI: https://www.realjoin.io/realjoin-agent.mjs
- MCP: https://www.realjoin.io/realjoin-mcp.mjs

The standalone MCP script must be stored next to `realjoin-agent.mjs` because it imports the shared zero-dependency client.

## MCP Client Configuration

```json
{
  "mcpServers": {
    "realjoin": {
      "command": "realjoin-mcp",
      "env": {
        "REALJOIN_API_KEY": "<optional-user-key>"
      }
    }
  }
}
```

Public read tools work without a key. Set `REALJOIN_API_KEY` only for confirmed account actions.

## Tools

- `realjoin_health`: Agent API health and service count.
- `realjoin_catalog`: complete agent catalog.
- `realjoin_services`: public service and package list.
- `realjoin_service_detail`: one service with fields, scenarios, and notes.
- `realjoin_quote`: local preview by default; `confirm=true` calls the quote API.
- `realjoin_order_preview`: local order-intent preview by default; `confirm=true` creates an intent.
- `realjoin_checkout`: local checkout preview by default; `confirm=true` may create a payable order.
- `realjoin_contact`: local Telegram handoff preview by default; `confirm=true` sends it.
- `realjoin_order_status`: reads an order with its query password.

## Safety

Write-capable tools never write by default. They return a structured preview with `writePerformed=false` and `paymentCreated=false`. A remote write is possible only when the caller explicitly sends `confirm=true` and provides a scoped API key through the environment.

The MCP server writes only JSON-RPC protocol messages to stdout. It never prints API keys or query passwords.