MCP Protocol Reference

QANATIX exposes an MCP (Model Context Protocol) server via Streamable HTTP at /mcp/.

Endpoint

POST https://api.qanatix.com/mcp/

Standard MCP Streamable HTTP transport. Compatible with any MCP client (Claude Desktop, Claude Code, Cursor, custom clients).

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_live_abc123...

In development mode, you can use X-Tenant-Id instead.

Call this first to discover what data is available. Returns a compact table of collections with record counts, categories, and descriptions. Does not include field schemas inline — use qanatix_schema for that.

Parameter	Type	Required	Default	Description
`query`	string	no	—	Filter collections by name or description substring
`category`	string	no	—	Filter by category tag
`limit`	integer	no	20	Max collections to return

Returns:

Table of collections with record type, record count, category, and description
Points to qanatix_schema(collection) for field details

qanatix_schema

Get field schema and filter options for a specific collection. Returns field names, types, sample values, and filter syntax guide.

Parameter	Type	Required	Description
`collection`	string	yes	Collection name (from `qanatix_collections` results)

Returns:

Field names with inferred types, sampled from collection data
Sample values for each field (up to 4 unique values)
Filter syntax guide (exact match, range, multi-value, etc.)

qanatix_search

Unified search tool — works with a query, filters, or both. Returns results with total count (e.g. "Showing 10 of 347 results").

Parameter	Type	Required	Default	Description
`query`	string	no	—	Natural language search query. Optional when filters are provided.
`collection`	string	yes	—	Collection to search
`filters`	object	no	—	Key-value filters (see filter syntax below)
`sort`	string	no	—	Sort field. Prefix with `-` for descending. E.g. `price_usd`, `-weight_kg`.
`limit`	integer	no	10	Results to return (1-50)
`offset`	integer	no	0	Skip N results for pagination
`format`	string	no	`markdown`	Output format: `markdown` or `json`

Note: When both query and filters are provided and full-text search returns no results, the query is automatically dropped and filters are retried alone (zero-result fallback).

Filter syntax

Filters are applied server-side before ranking. Short field names auto-resolve to collection_data.* paths.

Pattern	Operation	Example
`field=val`	Exact match	`{"brand": "SKF", "record_type": "product"}`
`field=val1,val2`	Multi-value (IN)	`{"manufacturer": "SKF,ABB,FAG"}`
`field_min=val`	`>=`	`{"price_min": "10", "stars_min": "4"}`
`field_max=val`	`<=`	`{"price_max": "100", "expense_ratio_max": "0.1"}`
`field_gt=val`	`>`	`{"score_gt": "0.5"}`
`field_lt=val`	`<`	`{"lead_time_days_lt": "10"}`
`field_in=val1,val2`	IN (explicit)	`{"status_in": "active,pending"}`

Use qanatix_collections() to discover which fields are available for filtering.

Example tool calls:

{
  "name": "qanatix_search",
  "arguments": {
    "collection": "manufacturing",
    "query": "stainless M8 bolt ISO 4017",
    "filters": {"in_stock": "True", "price_max": "0.20"},
    "limit": 5
  }
}

Filter-only (no query):

{
  "name": "qanatix_search",
  "arguments": {
    "collection": "manufacturing",
    "filters": {"manufacturer": "SKF,ABB", "price_max": "50"},
    "sort": "-price_usd",
    "limit": 20
  }
}

qanatix_aggregate

Count, group, and compute stats on records. Use this for questions like "how many products by brand?" or "what's the price range?"

Parameter	Type	Required	Default	Description
`collection`	string	yes	—	Collection to aggregate
`filters`	object	no	—	Same filters as search
`group_by`	string	no	—	Field to group by. Returns top values with counts.
`stats`	string[]	no	—	Numeric fields for min/max/avg. E.g. `["price_usd", "weight_kg"]`

Example:

{
  "name": "qanatix_aggregate",
  "arguments": {
    "collection": "manufacturing",
    "group_by": "manufacturer",
    "stats": ["price_usd", "weight_kg"]
  }
}

qanatix_list

Browse/paginate records in a collection. Kept for backward compatibility — qanatix_search with no query provides the same functionality with more options.

Parameter	Type	Required	Default	Description
`collection`	string	yes	—	Collection to browse
`record_type`	string	no	—	Filter by record type
`status`	string	no	—	Filter by status (active, draft, suspended)
`q`	string	no	—	Full-text search (supports OR, phrases, negation)
`filters`	object	no	—	Key-value filters (same syntax as `qanatix_search`)
`sort`	string	no	—	Sort field. Prefix with `-` for descending.
`cursor`	string	no	—	Pagination cursor from previous response
`limit`	integer	no	20	Results per page (1-50)

Returns a markdown table with pagination cursor for the next page.

qanatix_lookup

Get complete details for a specific record by UUID.

Parameter	Type	Required	Description
`record_id`	string	yes	Full record UUID from search or list results
`format`	string	no	Output format: `markdown` (default) or `json`

Returns YAML-formatted record with all fields including full collection_data.

Resources

record://{record_id}

Read-only access to a single record by UUID.

record://550e8400-e29b-41d4-a716-446655440000

Returns the same output as qanatix_lookup.

schema://{collection}/{record_type}

Read-only access to a collection's inferred field schema. Field names and types are auto-detected by sampling collection data.

schema://manufacturing/fastener

Returns field names with inferred types, sampled from collection data.

MCP vs REST

	MCP	REST API
Transport	Streamable HTTP	Standard HTTP
Auth	Bearer token	Bearer token
Tools	6 (collections, schema, search, aggregate, list, lookup)	Full CRUD + upload + admin
Format	Markdown or JSON (configurable)	JSON/compact/YAML (configurable)
Search limit	1-50	1-100
List limit	1-50	1-100
Ranking	Same	Same
Best for	Claude, Cursor, MCP clients	GPT, Gemini, LangChain, apps

The MCP server is optimized for AI consumption — compact output, total counts, and structured filters.

MCP Protocol Reference

On this page