The orgrelay-connector/1 spec

The contract between your system and OrgRelay, on one page. It is deliberately small: a manifest that lists your tools, a naming rule, a read/write flag, and a handful of conventions for errors, paging and time.

The machine-readable versions live in the developer kit's spec/ folder: connector-manifest.schema.json, event.schema.json, orgrelay-rest.openapi.yaml and standard-tools.json. This page explains them. If you only want to see them working, the quickstart runs a template that implements every rule here.

#The manifest

The manifest says who you are and which tools you offer. Where it lives depends on the transport:

• Over MCP, return it from resources/read as the resource orgrelay://connector/manifest.
• In REST compatible mode, serve it at GET {base}/manifest.

A minimal manifest:

{
  "spec": "orgrelay-connector/1",
  "name": { "en": "Sample ERP", "zh-CN": "示例 ERP" },
  "version": "1.0.0",
  "auth": { "type": "bearer" },
  "events": ["orders.created", "inventory.low_stock"],
  "tools": [
    {
      "name": "orders.search",
      "access": "read",
      "title": { "en": "Search orders" },
      "description": "Search orders by status or customer. Returns order_no, status, customer and total, newest first.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["pending", "paid", "shipped"] },
          "cursor": { "type": "string" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
        }
      }
    }
  ]
}

#Tools

Over MCP, inputSchema goes in tools/list and annotations.readOnlyHint must agree with access. If they disagree, OrgRelay treats the tool as write. That is the safe direction: a mislabelled tool costs an approval, never an unapproved change.

#Name tools after the standard domains

Fourteen domains have recommended names: orders, inventory, products, customers, purchase, logistics, finance, hr, tickets, seo, ads, content, tasks and reports. Using them lets OrgRelay route tools to department agents without configuration: the sales agent gets orders.* and customers.*, the warehouse gets inventory.*. The full list with input and output fields is on standard tools. For anything else, follow the same pattern, for example quality.inspections.

#Write good descriptions

The description is the only thing the AI reads when deciding which tool to call. Compare:

#Calling conventions

MCP. Streamable HTTP, protocol version 2025-06-18 (2025-03-26 compatible). OrgRelay passes context in tools/call params._meta: orgrelay/actor with the person's id, name, role and department; orgrelay/approval_id and orgrelay/idempotency_key on approved write calls. Return results in structuredContent and a JSON copy in content. Details on the MCP transport page.

REST. POST {base}/tools/{name} with { "arguments": { ... } }. The same context travels in headers: Idempotency-Key, X-OrgRelay-Actor (base64url JSON) and X-OrgRelay-Approval-Id. Details on REST compatible mode.

#Error codes

message is shown to people. It must not contain stack traces, SQL, file paths or tokens; the security page lists what else to keep out. OrgRelay passes 4xx business errors through to the AI and the user. Timeouts, 5xx and network errors count as failures. After three in a row, OrgRelay stops calling your connector for 60 seconds.

#Pagination

List tools accept cursor (omit it on the first page) and limit (default 20, maximum 100). They return { "items": [...], "next_cursor": "..." | null } and may add total. OrgRelay treats cursors as opaque strings, so an offset, a database key or a vendor's own cursor are all fine.

#Timeouts, limits and size

• OrgRelay waits up to 20 seconds per call. Aim for 95% of calls under 2 seconds and none over 5. For long jobs, return a job id and provide a second tool that fetches the result.
• By default OrgRelay sends at most 120 calls per minute per connection. Answering 429 with Retry-After is fine and does not count as a failure.
• At most 100 tools. Keep each result under about 100 KB; the AI sees roughly the first 12,000 characters.

#Money and time

• Money is { "amount": 18600, "currency": "CNY" }, with ISO 4217 currency codes.
• Dates are YYYY-MM-DD.
• Timestamps are ISO 8601 with an offset: 2026-11-09T10:00:00+08:00.

#Versioning

The spec version is the manifest's spec value. Within orgrelay-connector/1, only backward-compatible changes are made: new optional fields, tools, error codes and event types. OrgRelay ignores fields it does not know.

For your own connector:

• Adding tools or optional arguments is safe. Bump the minor version. When the owner clicks Test connection, new tools appear switched on, and the owner can switch them off.
• Never rename a tool, remove an argument, change its meaning or turn a read tool into a write tool. Add orders.search_v2 and keep the old tool for at least six months, marked deprecated in its description.
• When orgrelay-connector/2 arrives, OrgRelay will support both for at least 12 months. Changes are announced on the changelog.

#Common questions

Is the manifest the same as tools/list? No. tools/list is standard MCP. The manifest adds what MCP does not carry: read or write per tool, a four-language name, auth defaults and event types.

What if readOnlyHint and the manifest disagree? The tool is treated as write and goes through approval. The self-test tool reports it as a failure.

Can I add tools later? Yes, see versioning above.

#Next

• Run the self-test against your implementation.
• Read how write tools and approvals interact.
• Start from a template instead of a blank file.
• How the business owner controls which roles can use each tool is explained on orgrelay.com's integrations page.
• Start from a template that already follows every rule on this page.
• Pick a transport: MCP or REST compatible mode.
• When the API already exists, generate tools instead: OpenAPI import or GraphQL import.
• How staff reach your tools from their own AI client: MCP overview.

#Related pages

• Enterprise patterns: permissions, offboarding and data residency.
• Human-in-the-loop: why approvals live outside the AI client.