# AcuiQ for agents

AcuiQ matches symptoms to acupuncture point selections extracted from published
literature, each carrying its citation. Anonymous: no account, no API key, no
sign-up. This document is the operating manual; https://acuiq.com/llms.txt is the
briefing that says what the corpus contains.

## MCP endpoint

- **URL**: https://acuiq.com/api/mcp
- **Transport**: Streamable HTTP, JSON-RPC 2.0 over POST
- **Protocol version**: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 spoken, on one endpoint. A 2026-07-28 client puts its version and capabilities in `params._meta` on every request and can start with `server/discover`; an older client negotiates on `initialize` (newest offered: 2025-11-25). Every response echoes the version in `MCP-Protocol-Version`.
- **Server**: `acuiq` 1.1.0
- **Batching**: up to 20 requests per POST, and only under 2025-03-26 or earlier. Every later revision removed batching from the spec, so an array body is refused – send one request per POST.
- **GET** returns 405 with a pointer here. There is no SSE leg.
- **Discovery**: https://acuiq.com/.well-known/mcp.json, https://acuiq.com/.well-known/agent-card.json (A2A), https://acuiq.com/openapi.json (also at /.well-known/openapi.json and /api/openapi.json).

## Tool sequence

Resolve, then search, then read. Guessing a symptom name is the one thing that
reliably returns nothing:

1. `search_symptoms` – turn what the person said into AcuiQ symptom names. A plain description works; filler is stripped and the reduced term is reported back as `matchedTerm`.
2. `search_protocols` – pass the names it returned, not the description. Ten matches by default, `limit` up to 50. Point codes resolve against the `points` dictionary in the same response, which states each point once.
3. `get_symptom_detail` / `get_point` / `get_wiki_page` – one symptom, one acupoint, or the reference wiki when the question is what something MEANS rather than what to needle.

Every protocol row carries `sourceKind`, a human-readable `source` and a
`caveat` saying what the row is. Relay the caveat; it is not decoration.
`studyBacked: false` means no study covers the query at all, which is worth
saying before any protocol.

Full tool list:

- `search_symptoms` – Search symptom names
- `search_protocols` – Find treatment protocols
- `get_meridians` – List meridians
- `get_symptom_detail` – Get symptom detail
- `get_point` – Look up an acupoint
- `create_checkout` – Create checkout session **(writes – creates a live Stripe session)**
- `get_order` – Check order status
- `get_wiki_page` – Read a wiki page

To sell something, `create_checkout` returns a Stripe URL for the human to
open – never collect payment details yourself – plus a `session_id` to poll
`get_order` with. Leave a few seconds between polls.

## Markdown twins

Every page has a markdown twin at the same URL plus `.md`:

- https://acuiq.com/symptoms/{slug}.md – e.g. https://acuiq.com/symptoms/headache.md
- https://acuiq.com/points/{code}.md – e.g. https://acuiq.com/points/li04.md
- https://acuiq.com/wiki/{section}/{slug}.md – e.g. https://acuiq.com/wiki/nomenclature/point-codes.md

To read ALL protocols for one symptom, fetch the twin: one request, and far
smaller than paging `search_protocols`. Twins carry an `ETag` and a
`Last-Modified`, so a recrawl of an unchanged page costs a 304 and no body.
Send `If-None-Match`; the ETag is the precise validator, because no table here
carries a row timestamp and `Last-Modified` is the newest stamp the corpus as
a whole holds.

## Rate limit

60 requests per minute per IP, shared across every JSON-RPC method. `create_checkout`
is gated tighter than that (5/min per IP) because each call creates a live
Stripe session. Over budget, /api/mcp answers **429 with a JSON-RPC error
envelope** – `{code: -32000, message}` plus a `Retry-After` header – not a
bare `{"error": "..."}`. Back off on the header.

## Licence

AcuiQ-authored prose (symptom and meridian descriptions, the wiki, the auricular crosswalk) is licensed CC-BY-4.0: https://creativecommons.org/licenses/by/4.0/. The assembled protocol compilation is not: build on it with attribution, but do not redistribute it whole as a dataset – https://acuiq.com/terms. The underlying findings are the cited sources' claims – each entry carries its citation; verify against the source before relying on it. Not medical advice: https://acuiq.com/terms

## Licence & attribution

AcuiQ-authored prose – the symptom and meridian descriptions, every wiki page, the auricular crosswalk, and the atlas ear and scalp-line plates – is licensed under the Creative Commons Attribution 4.0 International (CC-BY-4.0): https://creativecommons.org/licenses/by/4.0/

You may ingest, embed, and redistribute this content in RAG systems, fine-tuning
datasets, or other derivative works, including commercially. Attribution at the
dataset or system level is sufficient.

- Recommended attribution: "Source: AcuiQ (https://acuiq.com), CC BY 4.0"
- SPDX identifier: CC-BY-4.0

THE ASSEMBLED COMPILATION IS LICENSED SEPARATELY. The protocol corpus – the
extraction, the resolution of every reference, and the arrangement – may be
used to build on, with attribution. It may not be redistributed whole or
substantially whole as a dataset, or as a product whose main value is access
to it. Terms: https://acuiq.com/terms

The body diagrams (muscular, dermal, skeletal layers and their point crops) are
not licensed for reuse.

The grant covers neither the compilation nor the underlying findings: each
protocol entry records what a cited published source prescribed – the facts
are the sources' claims, and each entry carries its citation. Verify against
the cited source before relying on an entry. None of this is medical advice:
https://acuiq.com/terms

## Not medical advice

Each entry records what a cited published source prescribed. Verify against the
cited source before relying on it, and say so when you relay it. Terms:
https://acuiq.com/terms