Tools, Resources & Prompts
xql_validate, xql_explain, xql_run, the NL reference resource, and the translate_query prompt.
Tools
The server registers exactly three tools, each taking a single required string argument, query, containing raw XQL text: the same text you'd send as the body of the equivalent HTTP API call.
| Tool | Equivalent to | Behavior |
|---|---|---|
xql_validate | POST /xql/validate | Parses and plans query, without touching any data store |
xql_explain | POST /xql/explain | Parses and plans query, returns the plan manifest and a human-readable explanation |
xql_run | POST /xql/run | Parses, plans, and executes query against market data |
All three produce results equivalent to their REST counterparts for the same query text: they call the identical underlying engine functions, not a separate implementation.
Errors Are Tool Errors, Not Protocol Errors
A parse failure, plan failure (including exceeding the 300-bar lookback ceiling), or, for xql_run, a downstream data-fetch failure, is reported as a tool result with isError: true and a content block describing the failure (the same {type, message, position?} shape the REST endpoints use), rather than an MCP protocol-level error. The MCP request itself still completes successfully; check isError on the tool result, not the request status.
Resources
Alongside the three tools, the server registers one resource:
| URI | MIME type | Content |
|---|---|---|
xql://nl-reference | text/markdown | The natural-language-to-XQL translation reference: the phrase-to-construct dictionary an LLM uses to translate retail-trader language into XQL and paraphrase results back |
Resources are best-effort
MCP hosts aren't required to auto-attach resources to an LLM's context: the
resource is available to any client that explicitly requests it
(resources/list then resources/read), but XCREENER doesn't depend on a
generic host surfacing it automatically. If you're building an integration and
want your LLM to have XQL translation context, read this resource explicitly
and include it yourself.
The resource read is gated by the same API-key check as the tools: a resources/read request without a valid key is rejected before any content is returned.
Prompts
Alongside the tools and resource, the server registers one prompt:
| Prompt | Argument | Behavior |
|---|---|---|
translate_query | humanQuery (string) | Returns the NL reference document plus an instruction to translate humanQuery into XQL, ready to check with xql_validate before calling xql_run |
Unlike the resource above, a prompt is meant to be invoked deliberately. Most clients surface a server's registered prompts as a discoverable, user-triggerable action (similar to a slash command) rather than leaving it up to the model to decide whether to go fetch context on its own. If your client supports MCP prompts, translate_query is the more reliable way to get the NL reference into context at the moment you actually need it, instead of hoping a host auto-attaches the resource.
The prompt is gated by the same API-key check as the tools and resource: a prompts/get request without a valid key is rejected before any content is returned.