Nia MCP tool reference

Available tools

No tool catalog is currently published here. This does not certify any operation as enabled. Ask Ariy for a verified business endpoint.

Requests and retries

Use Streamable HTTP JSON-RPC requests with a unique RPC ID. Send Accept: application/json, text/event-stream and Content-Type: application/json. Obtain thread authority with thread.start when advertised. Store the returned token privately. For subsequent operations, supply the token and a UUID requestId in arguments. Retry the same operation with the same requestId and unchanged arguments; changed input requires a new requestId.

A thread token expires after seven days and never establishes customer identity. A conversation admission lasts 24 hours from the first successful Nia answer. Resource reads, thread creation and saved enquiries do not consume a new conversation. Unavailable tools, capacity exhaustion and revoked tokens must not be presented as successful work.

A saved enquiry or human handoff receipt means pending owner follow-up. It is not a booking or a delivery receipt. See the connection and privacy guide.

Protocol and limits

The canonical endpoint is https://<verified-origin>/api/mcp/<immutable-business-handle>. The server accepts stateless Streamable HTTP POST with protocol versions 2025-03-26 and 2025-06-18. Initialize before discovery; no session ID or API key is required. Only approved origins may send browser-origin requests.

Resource URIs use mcp://business/<handle>/v1/<resource>, where resource is profile, services, hours, contact or faq. Discovery returns only published resources. Responses contain application/json public projections. No subscriptions or resource templates are offered.

Requests are limited to 20,000 bytes, 120 requests per business per minute and 3,000 across the gateway per minute. Thread creation is additionally limited to 60 per business per minute. Model messages are limited to 2,000 characters; enquiry summaries to 2,000. Limits include discovery and retries. Avoid polling.

Owners must approve both public facts and each tool. A thread token authorizes only its business and thread; it does not verify a person or grant customer-history access. The current schemas below are the runtime descriptors, not a promise that every business has those tools.

Synthetic examples

Replace the endpoint with the confirmed business endpoint. The examples use placeholders and synthetic request IDs. Discover tools before executing them, and obtain a fresh thread token from thread.start. Never submit a real person’s enquiry without their intent.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "nia.ask",
    "arguments": {
      "threadToken": "<token returned by thread.start>",
      "requestId": "00000000-0000-4000-8000-000000000001",
      "message": "Which of your published services covers website updates?"
    }
  }
}

A successful Nia response has status succeeded, a reply, a UUID receiptId, and metering admitted or existing_thread. The response is returned in structuredContent and the JSON text content block.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "inquiry.create",
    "arguments": {
      "threadToken": "<token returned by thread.start>",
      "requestId": "00000000-0000-4000-8000-000000000002",
      "name": "Example customer",
      "email": "customer@example.test",
      "summary": "Synthetic example: I would like to discuss a website update."
    }
  }
}

An enquiry or human_handoff.request returns status saved, a UUID reference, verification unverified, followup pending and metering not_charged. Use that reference when asking the business about the submitted request. No calendar event, notification delivery or response time is implied.

Errors and recovery

HTTP 404 means the business is unavailable; 403 rejects an origin; 429 means the rate limit was reached. Stop on an unavailable business and confirm its endpoint. After a rate limit, wait at least a minute with jitter. HTTP 400, 406, 413 and 415 require fixing the protocol, Accept header, payload size or content type. JSON-RPC -32601 means the method or tool is unavailable; -32002 means the resource is not public. Do not substitute another business’s URI or token.

Temporary failures return HTTP 503 with normalized JSON-RPC -32603. Tool outcomes may instead set isError with status busy, capacity_exhausted, temporarily_unavailable or action_unavailable. Follow retryAfterSeconds when present. Retry transient failures with bounded backoff and the same requestId and arguments. Changed input under an existing requestId is rejected. Capacity exhaustion needs business action, and an unavailable action must not be described as completed. No raw provider error or private context is returned.

Intake details are stored for the business’s follow-up. Operational request receipts retain method, timing, result and safe references for seven days, without raw prompts or thread tokens; business records have their own retention. Public facts must never contain private customer information.