orgrelay-connector/1 · spec 1.1.0
Connect your business systems to a self-hosted AI
OrgRelay runs on a company's own Mac mini and answers staff questions from company files and business systems. Every action that changes data waits for a person to approve it. This site is for the people who wire it up: in-house IT, outsourced developers and system integrators.
The three paths are ordered the way most teams meet them. The connector spec is the contract between your system and OrgRelay. The MCP guide covers the other direction, where OrgRelay is the server and the AI client on an employee's laptop is the caller. The connector directory is for platforms where someone has already written that contract, and OpenAPI import covers platforms that only describe their own API.
How a request moves through OrgRelay
A sales manager asks: "Which orders from last week are paid but not shipped?" OrgRelay picks the tool orders.search from the connector that the manager's role is allowed to use, calls your system with that company's token, and answers with the order numbers and where they came from. If the manager then says "Cancel SO-1002", OrgRelay does not call your system. It creates an approval request. Only after the owner approves does it call orders.update_status, with an idempotency key so a retry can never cancel twice.
| Step | What OrgRelay does | What your connector must do |
|---|---|---|
| Discover | Reads your manifest and tools/list |
Declare each tool as read or write |
| Authorise | Sends the tenant's token; checks the caller's role | Return only that tenant's data (tenant isolation) |
| Read | Calls read tools directly | Answer within 2 s where possible; paginate with cursors |
| Write | Creates an approval; calls after a person approves | Honour the idempotency key |
| Notify | Receives your events and alerts the owner | Sign each event with HMAC-SHA256 |
The business side of approvals, who signs off and what an owner sees, is described on the approvals page at orgrelay.com. This site sticks to the protocol.
Three ways to connect a system
If a vendor already ships its own MCP server, for example Shopify, HubSpot or Odoo, OrgRelay can connect to it directly. OrgRelay then adds what a vendor server usually lacks inside a company: per-role access, approval before writes and one audit log across every system.
What you can download today
- Developer kit 1.1.0 (MIT): the spec files, templates in Node.js, Python, PHP and Java, and the self-test tool
orgrelay-connector-check. - Machine-readable spec: manifest JSON Schema, event schema and the REST OpenAPI file.
- Standard tool names for 14 business domains, from
orders.*toreports.*, listed on the standard tools page.
Built for privately deployed AI
OrgRelay is installed inside the customer's network, usually next to the systems it talks to. That changes a few defaults compared with a SaaS integration:
- Your connector is called from the customer's LAN. An internal URL is normal; there is no OrgRelay cloud in the middle. See authentication for IP allow-lists and token rotation.
- Credentials are stored encrypted on the customer's machine. Only the last four characters are ever shown.
- Write calls carry the approver's identity in
orgrelay/actorandorgrelay/approval_id, so your own audit log can show who approved what. - Company-specific know-how, such as how to price a quotation, lives in Agent Skills folders rather than in prompts.
If you are evaluating OrgRelay for a company rather than building for it, the product overview and security page on orgrelay.com are the better starting point.
Where to go next
- New to OrgRelay connectors: Quickstart, then connector spec.
- Connecting an off-the-shelf platform: the connector directory, or OpenAPI import when the platform is not listed.
- Giving staff OrgRelay inside their AI client: Claude Code, Codex, enterprise MCP patterns.
- What changed in the spec: changelog.