OrgRelay
orgrelay.com

Quickstart: build and self-test a connector

You will run a working connector on your laptop, prove it behaves correctly with the self-test tool, and know exactly which two functions to replace with queries against your own system.

You need: Node.js 18 or later, a terminal, and the developer kit. Nothing else is installed; the Node template has no third-party dependencies.

1. Get the developer kit

The kit is a plain folder: spec files, four templates and the self-test tool. It is MIT licensed. Download it from the examples page, unzip it, and open a terminal in the folder.

Developer kit layout
orgrelay-developer-kit/
├── bin/orgrelay-connector-check.mjs   # self-test tool
├── spec/
│   ├── connector-manifest.schema.json # manifest JSON Schema
│   ├── event.schema.json              # event push format
│   ├── orgrelay-rest.openapi.yaml     # REST compatible mode
│   └── standard-tools.json            # 14 domains, input and output schemas
└── templates/                         # Chinese comments; templates/en/ has English comments
    ├── node/server.mjs
    ├── python/server.py
    ├── php/server.php
    └── java/ConnectorServer.java

Each file is explained elsewhere: the schemas on the connector spec page, the domain tools on standard tools, and the templates on code templates.

2. Start the template

Every template serves both transports from one process: MCP on /mcp and REST compatible mode on /orgrelay/*. Tokens map to tenants through one environment variable. Use two long random strings so the self-test can check that tenant B never sees tenant A's data.

Node.js
export CONNECTOR_TOKENS="$(openssl rand -hex 24):tenant-a,$(openssl rand -hex 24):tenant-b"
echo "$CONNECTOR_TOKENS"   # keep both tokens for step 3
node templates/en/node/server.mjs

The server listens on port 8787 and logs one line per request, including the tenant it resolved from the token. That log line is the first thing to check if the self-test reports a tenant problem.

3. Run the self-test

In a second terminal, pass tenant A's token as --token and tenant B's as --token-b. --write exercises the write tool, which is fine here because the template only holds sample data.

Terminal
node bin/orgrelay-connector-check.mjs http://127.0.0.1:8787/mcp \
  --token <tenant-a-token> --token-b <tenant-b-token> --write --lang en

This is the output we got from the unmodified Node template on 12 November 2026:

Output (shortened)
OrgRelay connector check 1.1.0 · MCP · http://127.0.0.1:8787/mcp

【Auth】
  ✔ PASS  no token → 401  — HTTP 401
  ✔ PASS  wrong token → 401  — HTTP 401
  ✔ PASS  valid token connects  — HTTP 200
【Manifest】
  ✔ PASS  spec = "orgrelay-connector/1"
  ✔ PASS  tool names are domain.action
  ✔ PASS  readOnlyHint consistent
【Errors】
  ✔ PASS  unknown tool returns a proper error
  ✔ PASS  wrong argument types → invalid_arguments (orders.get)
【Idempotency】
  ✔ PASS  inventory.adjust: same key twice returns the first result
【Tenant isolation】
  ✔ PASS  orders.search: tenant B does not see tenant A data

Result: PASSED · PASS 28 · FAIL 0 · WARN 0 · SKIP 0

Run it a second time against REST mode with --mode rest and the base URL http://127.0.0.1:8787/orgrelay. Without --write you get 25 passes and one skip for idempotency. What each check means, and how to fix a failure, is on the self-test tool page.

4. Replace the sample data

Open the template. Two things are sample-only:

In the template Replace with
DATA, an in-memory object per tenant Your database, or calls to your system's API
run(tenant, name, args, idemKey), a switch per tool One query per tool, filtered by tenant first
TOOLS, the four tool definitions Your tools, named after the standard tools where they fit

Keep the rest: the token check, the error mapping and the idempotency store. Those parts are what the self-test verifies, and they follow the rules in approvals and write tools and security requirements.

5. Bind it to OrgRelay in sandbox mode

Ask the company's OrgRelay owner to add the connection with Developer mode (sandbox) ticked and your test URL. Staff and the AI cannot use a sandbox connection. The owner can call any tool by hand, including write tools, watch each call arrive, and see the events you push.

  1. Owner opens Admin → Business systems → Add connection.
  2. Chooses MCP and enters https://your-host/mcp, or REST compatible mode with https://your-host/orgrelay.
  3. Pastes tenant A's token and clicks Test connection. OrgRelay lists the tools it found.
  4. When you are ready, the owner clicks Promote to live and grants the connector to roles or departments.

How the owner decides which roles may use which tools is covered for business readers on orgrelay.com's integrations page.

6. Before you hand it over

  • Run the self-test against production without --write and add --json. Give that report to the customer.
  • Check that error messages contain no stack traces, SQL or file paths. The self-test flags common leaks, but read a few errors yourself.
  • If your system can tell OrgRelay about new orders or low stock, add event push.

Common questions

Do I need a public URL? No. OrgRelay usually sits in the same LAN as your system, so http://10.0.0.12:8787/mcp is normal. Across networks, use a VPN or a reverse proxy; never expose an unauthenticated API.

Which language should I use? The one your system is written in. All four templates implement the same tools, error codes and idempotency rules. The Node.js, Python and Java templates each passed all 28 checks when we ran them for this guide.

Is --write safe? Only against a test environment. It calls a write tool twice with the same key to prove the second call does nothing, so the first call does change data.

Next steps

Updated (Singapore time) · OrgRelay Team