Vascue Public Knowledge Search

Vascue Public Knowledge Search (MCP server)

A Model Context Protocol server that searches Vascue's public documentation: healthcare operations, Vascue Front Desk for clinics, provider-side insurance claims automation, practice-management integrations (two-way sync with Cliniko and Nookal; Jane, Mindbody, PracticeHub, HexaHealth, Halaxy, Clinicea, ClinicOffice, Semble, Plato Medical and JERA in progress), security, case studies and pricing.

It comes in two equivalent forms:

• Hosted (always current): https://www.vascue.io/mcp/search - streamable HTTP, no authentication.

• Self-contained (this repo): python server.py - local BM25 search over a bundled snapshot of the public pages (content/, refreshed per release with scripts/fetch_content.py). No network calls at runtime, so it also works offline and is what directory-built releases run.

• Endpoint: https://www.vascue.io/mcp/search (streamable HTTP, no authentication)

• Server card: https://www.vascue.io/.well-known/mcp/server-card.json

• Registry name: io.vascue/public-knowledge-search

• Operated by: Vascue Limited (ISO 27001 certified)

Public content only. This server indexes public product and educational pages. Never send patient information, claim documents, clinic credentials or booking requests to it. Agent-based clinic booking is a separate research pilot, not a public API.

Connect

Any MCP client that speaks streamable HTTP can connect to the endpoint directly.

Claude Code

claude mcp add --transport http vascue-search https://www.vascue.io/mcp/search

Cursor / Claude Desktop / other stdio-only clients (via mcp-remote)

{
  "mcpServers": {
    "vascue-search": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.vascue.io/mcp/search"]
    }
  }
}

Self-contained local server (stdio; bundled snapshot, no network)

pip install -r requirements.txt
python server.py

Docker (builds the self-contained server)

docker build -t vascue-public-knowledge-search .
docker run -i --rm vascue-public-knowledge-search

Tools

One tool, search, in both forms: no authentication, read-only. The inputs differ between the hosted endpoint and the local server.

Hosted endpoint (https://www.vascue.io/mcp/search)

Hybrid (keyword + vector) search over Vascue's public pages. Returns matching excerpts with their canonical https://www.vascue.io/... URLs so answers can cite the source.

Input	Type	Notes
query	string (required)	Natural-language question or keywords, e.g. "how does Vascue handle insurance claim pre-authorisation".
ai_search_options.retrieval.retrieval_type	"hybrid" | "vector" | "keyword"	Default hybrid.
ai_search_options.retrieval.max_num_results	integer 1–50	Default 8.
ai_search_options.retrieval.match_threshold	number 0–1	Default 0.35.
ai_search_options.retrieval.context_expansion	integer 0–3	Neighbouring chunks to include.

Query rewriting and reranking are disabled server-side; the server returns source chunks only and never a generated answer, so nothing is presented as a Vascue statement without a citation. Rate limit: 60 requests per minute per client.

Example call:

{ "name": "search", "arguments": { "query": "Cliniko integration for Vascue Front Desk" } }

The endpoint is backed by a Cloudflare AI Search instance over the approved public Markdown export of vascue.io (the service descriptor at https://www.vascue.io/.well-known/ai-search.json states what is and is not indexed).

Local server (server.py)

BM25 keyword search over the bundled content/ snapshot. No network calls at runtime. Returns {"chunks": [...]}, each chunk with url, title, score (0–1, relative to the best match) and text.

Input	Type	Notes
query	string (required)	Natural-language question or keywords; 3–15 words, one topic per call.
max_num_results	integer 1–50	Default 8.

Example call:

{ "name": "search", "arguments": { "query": "Cliniko integration", "max_num_results": 5 } }

Development

docker build -t vascue-public-knowledge-search .
node scripts/smoke.mjs docker run -i --rm vascue-public-knowledge-search   # initialize -> tools/list
node scripts/smoke.mjs npx -y mcp-remote https://www.vascue.io/mcp/search --transport http-only

CI runs the same build and smoke test on every push and weekly, so the badge above doubles as an endpoint health indicator.

Directory build specs

Directories that build the server from source (e.g. Glama) run the self-contained form. Generated build images vary (uv-managed Python without pip, or a PEP 668 externally-managed system Python), so use an explicit venv:

• Build steps: ["uv venv /opt/venv && uv pip install --python /opt/venv/bin/python -r requirements.txt"]
• CMD: ["/opt/venv/bin/python", "server.py"]
• No environment variables.

Where a normal pip exists, plain pip install -r requirements.txt + ["python", "server.py"] works too.

pip install -r requirements.txt
SMOKE_CALL_QUERY="Cliniko integration" node scripts/smoke.mjs python server.py   # local server
node scripts/smoke.mjs python bridge.py                                          # stdio bridge to the hosted endpoint
python scripts/fetch_content.py                                                  # refresh the content/ snapshot

Other machine-readable surfaces

• https://www.vascue.io/llms.txt
• https://www.vascue.io/openapi.json (public, read-only content API)
• https://www.vascue.io/.well-known/agent-skills/index.json (agent skills; also at vascue-io/skills)

Licence

This repository (README, manifest, Dockerfile) is MIT licensed. The content served by the endpoint is Vascue's public website content.