Tenant tool authoring
This capability belongs to the Wave A tenant-tool rollout. The registration mutation, the webhook executor, and the Cedar policy gate described below are specified in a decision record that has not yet completed adversarial review or founder ratification, and the substrate is not yet deployed. This page documents the contract your integration will use once Wave A ships, so you can build against it ahead of general availability. Nothing here is a commitment to a ship date.
Every tool available through Nebbos MCP falls into one of two ownership tiers. This is a separate axis from the Guest, Host, and Architect authentication tiers — a tenant tool can be called by an operator at any of those three tiers, and the two words “tier” mean different things on this page and on that one.
| Ownership tier | Built by | Ships via | Available to |
|---|---|---|---|
| Tier 1 — Core tools | Nebbos MCP Team | nebos-backend release | Every tenant |
| Tier 2 — Tenant tools | Your organisation | register_tenant_tool at runtime | Your tenant only, unless you opt in to sharing |
What Tier 2 tools are
Core tools cover what Nebbos ships out of the box: Pearl queries, task and project operations, the audit chain, and so on. They do not cover the systems specific to your organisation — your ticketing backlog, your internal approval queue, your proprietary scoring model. Tier 2 tools close that gap without requiring a Nebbos MCP Team release: you register a tool that points at an HTTPS endpoint you operate, and from that point forward it is callable, through the same MCP surface as every core tool, by the operator identities in your tenant.
Registration is a runtime mutation, not a code contribution. There is no PR against nebos-backend, no review queue on the Nebbos side beyond the automated checks described below, and no waiting for a Nebbos release. You own the tool’s logic entirely; Nebbos owns dispatch, policy evaluation, response scrubbing, and the audit trail.
Register a tool
Registration is one MCP tool call: mcp__nebos__register_tenant_tool.
{
"tool": "mcp__nebos__register_tenant_tool",
"input": {
"name": "acme_open_invoices",
"description": "Look up open invoices for a customer by account ID.",
"input_schema": {
"type": "object",
"properties": {
"account_id": { "type": "string" }
},
"required": ["account_id"]
},
"executor_url": "https://tools.<YOUR_DOMAIN>/nebbos/open-invoices",
"executor_signing_key_id": "<NEBBOS_KEY_ID>",
"visible_to_tenants": []
}
}| Field | Required | Notes |
|---|---|---|
name | Yes | Unique within your tenant. Callers see this alongside your core-tool roster in list_available_tools. |
description | Yes | Shown to the calling model. Write it the way you would document any tool — what it does, what it needs, what it returns. |
input_schema | Yes | A JSON Schema object, capped at 32 KiB. Cyclic $refs, oversized enum arrays, and regex-DoS-prone pattern constraints are rejected at registration — this validation runs before your schema is stored, so a bad schema fails the registration call rather than surfacing as a runtime incident. |
executor_url | Yes | Must be HTTPS. Before Nebbos activates the endpoint for live calls, you complete a domain-ownership challenge (a DNS TXT record or an HTTP well-known file, in the shape of an ACME HTTP-01 challenge) — this stops a rogue registrant from pointing dispatch traffic at a victim’s endpoint under the Nebbos identity. |
executor_signing_key_id | Yes | The identifier of a Nebbos-issued signing key. Nebbos uses the corresponding key material to sign every outbound request to your endpoint — see Signing. |
visible_to_tenants | No, defaults to [] | Cross-tenant sharing opt-in. See Visibility. |
A successful registration returns a tool_id and a status indicating whether the domain-ownership challenge is still outstanding. Until that challenge completes, the tool is registered but not dispatchable — calls against it are refused rather than silently dropped.
Webhook contract
Your executor_url receives a POST for every call Nebbos dispatches to your tool.
What Nebbos sends
POST /nebbos/open-invoices HTTP/1.1
Host: tools.<YOUR_DOMAIN>
Content-Type: application/json
X-Nebbos-Idempotency-Key: 7c1e2f2a-...-9b4d
X-Nebbos-Signature: <see Signing>
X-Nebbos-Timestamp: 1758812400
X-Nebbos-Key-Id: <NEBBOS_KEY_ID>
{
"tool_id": "acme_open_invoices",
"tenant_id": "<YOUR_TENANT_ID>",
"input": { "account_id": "CUST-4471" },
"request_id": "req_01H8YMK7ZQV3D4XCJ9RM8W2N5T"
}What your endpoint MUST do
Accept the idempotency key
Every dispatch carries a fresh X-Nebbos-Idempotency-Key. If your tool has side effects, dedupe on this key — a caller-side retry of the surrounding tool call can produce a second dispatch of the same logical request with a new request_id but is not expected to reuse the idempotency key across genuinely distinct calls.
Respond within your declared timeout
Wave A’s default per-tool timeout budget is 10 seconds. Nebbos does not retry a timed-out or unreachable call — retry policy on failure belongs to the MCP caller, not to the executor client. Design your endpoint to fail fast rather than hold the connection open on the hope of a slow success.
Return a JSON envelope, capped at 256 KiB
{
"result": { "open_invoices": [ /* ... */ ] }
}A response body over 256 KiB is refused before it reaches Nebbos’s response-scrubbing layer, and the caller receives tenant_tool_response_too_large instead of your payload. The cap exists so a compromised or malfunctioning tenant endpoint cannot hand the scrubber’s regex-based pattern matching a string engineered to run pathologically long — keep responses to what the calling model actually needs.
Never assume a retry will arrive
Because Nebbos does not auto-retry on your side of the connection, a transient failure on your end is visible to the caller as a typed error (see Errors) on that attempt, not smoothed over invisibly. Build your endpoint to be reliable on the first attempt rather than relying on Nebbos absorbing occasional failures.
Signing
Every outbound request to your executor_url is signed by Nebbos, keyed by the Nebbos-issued signing key you supplied at registration (executor_signing_key_id). The signature covers the canonical request — method, path, a hash of the body, the timestamp, and a nonce — rather than the raw bearer-token pattern, so a captured signature cannot be replayed against a different request or after its short expiry window.
The exact byte-level canonicalisation and header names below reflect the current decision record for the Wave A executor (X-Nebbos-Signature, X-Nebbos-Timestamp, X-Nebbos-Key-Id, X-Nebbos-Idempotency-Key). Treat the header names as illustrative until the build lands — verify against the final MCP onboarding artifact before shipping a production verifier.
Verification shape, once the exact canonicalisation is finalised:
Python
import hmac, hashlib, time
def verify(method: str, path: str, body: bytes, timestamp: str, nonce: str,
signature: str, key_material: bytes, max_skew_seconds: int = 300) -> bool:
if abs(time.time() - int(timestamp)) > max_skew_seconds:
return False # reject stale or forward-dated requests
body_hash = hashlib.sha256(body).hexdigest()
canonical = f"{method}\n{path}\n{body_hash}\n{timestamp}\n{nonce}"
expected = hmac.new(key_material, canonical.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)Reject the request if verification fails, if the timestamp is outside your accepted skew window, or if you have seen the nonce before. Do not process the body before verifying the signature.
Errors
When your tool fails to execute cleanly, the MCP caller never sees a bare HTTP status from your endpoint. Nebbos translates the failure into one of a fixed set of typed errors:
| Error | When it fires |
|---|---|
tenant_tool_timeout | Your endpoint did not respond within the per-tool timeout budget. |
tenant_tool_unreachable | DNS resolution, TCP connect, or TLS handshake failed against executor_url. |
tenant_tool_5xx | Your endpoint returned a 5xx status. |
tenant_tool_ssrf_blocked | The resolved IP for your executor_url failed the egress deny-list check (private ranges, link-local, cloud-metadata addresses) at connect time. If you see this against a legitimate endpoint, check whether your DNS is resolving to an address in one of those ranges. |
tenant_tool_response_too_large | Your response body exceeded 256 KiB. |
A Cedar policy decision can also refuse a call before it ever reaches your endpoint. That refusal arrives at the MCP caller as a distinct, plain-English envelope — never the raw internal policy tokens:
{
"error": "cedar_denied",
"reason": "Your organization requires human approval for this tool. Your admin has been notified.",
"audit_id": "<uuid>",
"appeal_path": "contact your tenant admin"
}Every tenant-tool call is evaluated against a dedicated Cedar action group, Action::"TenantToolCall", gated by the same three-outcome model — allow_autonomous, allow_with_hitl, deny — used across the rest of the platform’s policy layer. New tenant tools default to allow_autonomous; a tenant admin can put an individual tool into sandbox mode for test and debug cycles, which routes its calls through human-in-the-loop review instead. Governance-voice policy your organisation writes can also gate specific tools more tightly than the default. See MCP reference for how Cedar composes with the rest of the tool-dispatch path.
Visibility
A newly registered tool is visible only to your own tenant — callers in other tenants do not see it in their list_available_tools response, and cannot invoke it even by name. This is the default and requires no configuration.
To share a tool with a specific partner tenant, add their tenant UUID to visible_to_tenants:
{
"tool": "mcp__nebos__update_tenant_tool_visibility",
"input": {
"tool_id": "acme_open_invoices",
"visible_to_tenants": ["<PARTNER_TENANT_ID>"]
}
}There is no wildcard sharing in Wave A — you cannot make a tool visible to every tenant on the platform. Sharing is always an explicit, enumerated allowlist. This is deliberate: an empty-by-default list cannot silently widen, the way a global catalog with an afterthought filter can when the filter is forgotten somewhere downstream.
Removing a tenant from visible_to_tenants revokes their visibility on the next discovery read; it does not retroactively invalidate a call already in flight.
Lifecycle
Unregistering a tool. Call mcp__nebos__unregister_tenant_tool with the tool_id. The tool immediately drops out of list_available_tools for every tenant it was visible to. In-flight calls that were already dispatched are not interrupted; no new calls are accepted afterward.
Listing your tools. mcp__nebos__list_tenant_tools returns every tool your tenant has registered, including ones shared with you by a partner tenant, with their current visibility and domain-verification status.
Changing a tool’s schema. Wave A does not specify a dedicated versioning field. If you need to make a breaking change to input_schema — removing a required field, changing a type — register a new tool under a new name rather than mutating the existing one in place, so that callers holding a stale discovery snapshot do not send a shape your endpoint no longer accepts. Non-breaking additions (new optional fields) can be applied by unregistering and re-registering under the same name; there is no in-place schema-patch call in Wave A.
Audit and observability
Every dispatch to your executor_url writes one entry to the hash-chained audit log with three-way attribution:
calling_user_id— the operator identity whose MCP session invoked the tool.tenant_id— the tenant that owns the tool.nebbos_service_actor_id— the Nebbos service identity acting as the dispatching proxy.
The same request_id that appears in the dispatch body to your endpoint is the correlation key across the whole path — your own request logs and the Nebbos audit-chain entry for that call share it, so a support investigation can walk both sides without guessing at timing correlation.
Query your tenant’s dispatch history through the standard audit-chain tools — audit_event_list, audit_event_get, audit_event_hash_chain_verify — filtered to your tenant_id and the TenantToolCall action. See The audit chain for the record fields and how records are checked, and MCP reference for the tier requirement on those tools (Host tier).
Rate limits and fair use
The per-tenant executor rate limit is a separate mechanism from the platform-wide per-tier ceilings on REST, MCP, and CLI traffic — this one applies specifically to outbound dispatch against your executor_url, regardless of which operator tier placed the call. Wave A’s default is 60 calls per minute per tenant, with the ceiling for high-volume tenants tied to SKU tier rather than granted ad hoc.
A call that exceeds the executor-layer rate limit is refused before dispatch; it does not count against your endpoint’s own request budget, and it does not consume the timeout window.
Testing
A minimal executor that verifies the signature and echoes a result:
from flask import Flask, request, jsonify
app = Flask(__name__)
SIGNING_KEY = b"<key material resolved from your Nebbos-issued key id>"
@app.post("/nebbos/open-invoices")
def open_invoices():
if not verify(
"POST", "/nebbos/open-invoices", request.get_data(),
request.headers["X-Nebbos-Timestamp"], request.headers.get("X-Nebbos-Nonce", ""),
request.headers["X-Nebbos-Signature"], SIGNING_KEY,
):
return jsonify({"error": "signature_invalid"}), 401
account_id = request.json["input"]["account_id"]
return jsonify({"result": {"open_invoices": lookup(account_id)}})Register it against a sandbox tenant before pointing executor_url at production infrastructure:
{
"tool": "mcp__nebos__register_tenant_tool",
"input": {
"name": "acme_open_invoices_test",
"description": "Sandbox copy of acme_open_invoices for integration testing.",
"input_schema": { "type": "object", "properties": { "account_id": { "type": "string" } }, "required": ["account_id"] },
"executor_url": "https://staging-tools.<YOUR_DOMAIN>/nebbos/open-invoices",
"executor_signing_key_id": "<NEBBOS_STAGING_KEY_ID>"
}
}Complete the domain-ownership challenge on the staging endpoint, invoke the tool through an MCP client authenticated against your sandbox tenant, and confirm you see the dispatch as an audit-chain entry before promoting the tool to a production executor_url.