The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Stock Trends Market Intelligence listing page.
Local Model Context Protocol (MCP) adapter for public Stock Trends API resources.
This repository is a thin local stdio adapter over the front-facing Stock Trends API. It has no independent analytical authority of its own.
Authority flows in one direction only:
The MCP adapter:
Public resources and the default/free mode described below are credential-free: no API key, subscription, or payment credential is required to install, inspect, or use them. The conditional paid ST-IM execution path is a separate, explicitly gated surface that is disabled by default (see Conditional Paid ST-IM Tools). An additional default-off x402 posture can expose the same paid semantic tool names. Relay plus challenge flags preserve the local mock-only behavior; a distinct third live flag may enable a capped, one-request no-key challenge path. Neither x402 mode accepts or forwards proof, sends a payment header, returns paid data, pays, or spends.
New here? Start with the Default / Free Mode Quickstart below to install and run the server credential-free, then Connect a local stdio MCP client to wire it into an MCP client, and read Paid Mode Configuration and the Security Model before setting any paid variable.
This is the recommended first path for installing or inspecting the server. In default mode, the server:
stocktrends_estimate_workflow_cost.Using only the existing project scripts:
This git clone + npm install + npm run build sequence, followed by local stdio execution of the compiled dist/server.js, remains fully supported and is the primary install channel for this repository. This package is also publicly available from the npm registry as @stocktrends-publications/stocktrends-mcp-server — see Public npm Installation directly below. A third, distinct install path — a locally built npm package artifact (a local .tgz, not a registry install) — has also been validated cross-platform; see Local Package Artifact Installation below and the Cross-Platform Package Install / Stdio Validation Report.
No environment variables or .env file are required for this path. Do not set STOCKTRENDS_ENABLE_PAID_TOOLS, STOCKTRENDS_API_KEY, or STOCKTRENDS_ENABLE_PAID_EXECUTION while testing default/free mode.
Optional: npm start starts the local stdio server process directly and is mainly useful as a manual smoke check (it will sit waiting for JSON-RPC input on stdin). Stop it with Ctrl+C before launching the server via MCP Inspector below.
This package is publicly published to the npm registry as @stocktrends-publications/stocktrends-mcp-server. Anyone can install it by name, credential-free, without cloning this repository:
For a reproducible install pinned to an exact release, append @<version> (for example @1.0.0) to the command above; omit the version to receive the latest published release. Once installed, the package provides an npm-managed command shim (not a checkout-relative dist/server.js path) — see Connect a local stdio MCP client below for configuration examples covering both a package-installed shim and a checkout-relative path.
The 1.0.0 release was verified byte-for-byte (SHA-256) against its frozen, offline-validated release-candidate artifact before publication, and anonymous installation by name plus a Windows MCP initialize/list-only handshake were validated against the published package (see docs/SECURITY_MODEL.md §18 and the MCP Registry Readiness Implementation Notes). Version 1.0.1 prepares this package's official MCP Registry identity (com.stocktrends/market-intelligence, declared in server.json); MCP Registry publication itself is a separate, later, explicitly authorized step and is not claimed as complete by this README.
In addition to the public npm install above, this repository's package can also be built and packed locally as an installable npm artifact — on Windows and WSL2 Ubuntu (see the Cross-Platform Package Install / Stdio Validation Report). This path is useful for testing an unreleased local build against the published package's identity; it is not required for normal installation.
.tgz is committed, and none ships with a checkout.package.json carries the same public identity the published npm package uses: the scoped name @stocktrends-publications/stocktrends-mcp-server, the MCP Registry identity mcpName com.stocktrends/market-intelligence, and an explicit public publishConfig (access: public, the public npm registry) — see the Package Publication Configuration Implementation Notes and the MCP Registry Readiness Implementation Notes.To build the local artifact yourself from a checkout:
This produces stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz in the current directory — the reviewed closed artifact allowlist is dist/**/*.js, dist/**/*.d.ts, README.md, and LICENSE (see the Package Metadata and Closed Artifact Allowlist Implementation). Install it into a separate consumer project (not this checkout):
This local-artifact path and the Public npm Installation path above install the same reviewed package identity through two different channels; prefer the public npm install unless you specifically need to test an unreleased local build.
Once installed, the package provides an npm-managed command shim rather than a checkout-relative dist/server.js path. On POSIX systems (Linux, macOS, WSL) this is a symlink at node_modules/.bin/stocktrends-mcp-server; on Windows it is a generated shim at node_modules\.bin\stocktrends-mcp-server.cmd. Do not assume the bin is installed globally — resolve it from the consumer project's own node_modules/.bin. See Connect a local stdio MCP client below for package-installed client configuration examples alongside the checkout examples.
After building (npm run build), point the MCP Inspector at the compiled stdio server, with no paid-mode environment variables set:
In the Inspector UI, confirm:
stocktrends_estimate_workflow_cost, and the paid tools (stocktrends_get_stim_latest, stocktrends_get_stim_history, stocktrends_get_indicators_latest, stocktrends_get_indicators_history, stocktrends_get_selections_latest, stocktrends_get_market_regime_latest, stocktrends_get_market_regime_history, stocktrends_get_breadth_sector_latest, stocktrends_get_leadership_summary_latest) are not visible.stocktrends://api/openapi, stocktrends://ai/context) are listed and readable without any credential configured.This check confirms the free/default boundary without requiring or triggering any paid execution.
For a fuller step-by-step Inspector procedure — default/free listing, paid-exposed listing without execution, and a rollback checklist — see the Phase 5A MCP Inspector Validation Runbook (its paid-exposed surface and resource counts were correct when written for the Phase 4-era three-tool surface; current counts are documented in this README).
Free/default mode needs no API key, so nothing secret is involved in this quickstart. Always test and demonstrate default mode without a key. The full credential-handling rules — placeholders only, never commit or paste a real key — are consolidated in the top-level Secret Safety section.
This section wires the server into an MCP client over local stdio. Two installation shapes are covered, clearly separated in each subsection below:
npm run build): launches the compiled entry point directly with command: "node" and args: ["<absolute-path-to-checkout>/dist/server.js"], where <absolute-path-to-checkout> is the absolute path to this repository on your machine.<path-to-consumer-project>, the absolute path to the separate project where you ran npm install <path-to-local-...-1.0.1.tgz> (or npm install @stocktrends-publications/stocktrends-mcp-server — see Public npm Installation) — not this repository checkout, and not a global install.Every primary example in this section is free mode: no STOCKTRENDS_* variable is set, no API key is configured, and no spend is possible. Read Secret Safety before adding any paid variable to a client configuration file.
Free-mode mcpServers entry (no env block — credential-free by default):
Windows JSON paths must use either double backslashes ("C:\\Users\\you\\stocktrends-mcp-server\\dist\\server.js") or forward slashes ("C:/Users/you/stocktrends-mcp-server/dist/server.js") — a single backslash is not valid JSON.
The Claude Desktop configuration file location is client-version dependent; at the time of writing it is:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonVerify these paths against your installed Claude Desktop version's current documentation before relying on them, since client versions can change file locations and schema.
Package-installed variant (local artifact path, free mode). Uses the npm-installed command shim instead of a checkout-relative path:
Windows equivalent (the generated .cmd shim):
<path-to-consumer-project> is the absolute path to the separate project where you ran npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz> (or npm install @stocktrends-publications/stocktrends-mcp-server) — never this repository checkout, and never a global install path.
Optional paid-exposure variant (exposure only — not execution). This adds the paid tool definitions to the client's tool list; it does not authorize or perform any paid API call:
Exposure (STOCKTRENDS_ENABLE_PAID_TOOLS + a key) and execution (the separate STOCKTRENDS_ENABLE_PAID_EXECUTION flag, plus mandatory pricing preflight, nonzero caps, and a covering budget — see Paid Mode Configuration) are two separate gates: this variant leaves execution unset, so exposure alone can never send a request or spend. See the Phase 5A Operator Safety and Release Checklist §4 for the paid-execution eligibility checklist — it is not a live-execution runbook.
Persisted-config credential warning. A Claude Desktop config file is plaintext and persists on disk across restarts. If you place a real API key here for a deliberate, operator-supervised session, remove it again immediately afterward and restore the free-mode entry above — do not leave a real key sitting in a client configuration file.
Boundary note: Claude Code is an agentic client, and Phase 5D approval does not extend to autonomous agent paid execution. The documented Claude Code path is therefore free mode only, where the only tool is credential-free and no spend is possible. Paid exposure/execution remains a separate, operator-shell, operator-supervised procedure under Paid Mode Configuration and the eligibility checklist referenced above, and is deliberately not given a Claude Code recipe.
Register the server locally with the Claude Code CLI:
This registers a free-mode stdio server with no env entries. Equivalently, a project-scoped .mcp.json entry has the same shape (an entry with command and args and no type/url field is read as a stdio server):
Package-installed variant (local artifact path, free mode, POSIX):
Package-installed variant (local artifact path, free mode, Windows):
<path-to-consumer-project> is the absolute path to the separate project where you ran npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz> (or npm install @stocktrends-publications/stocktrends-mcp-server) — never this repository checkout, and never a global install path.
Any MCP client that supports local stdio servers can use this client-agnostic shape:
Package-installed variant (local artifact path, free mode). POSIX:
Windows (the generated .cmd shim):
<path-to-consumer-project> is the absolute path to the separate project where you ran npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz> (or npm install @stocktrends-publications/stocktrends-mcp-server) — never this repository checkout, and never a global install path.
Optional paid-exposure variant (same rules as Claude Desktop above — exposure only, execution flag absent):
Exposure is not execution: no request and no spend occurs until STOCKTRENDS_ENABLE_PAID_EXECUTION is additionally set to true and the mandatory pricing preflight, nonzero local caps, and a covering budget cap all pass (see Paid Mode Configuration). Paid execution is not documented here as a casual runbook; treat it as an eligibility checklist, not a copy-paste recipe.
MCP Inspector remains a useful diagnostic/operator tool for confirming the server's tool, resource, and prompt surface — see Inspect with MCP Inspector above — but it is not the only, or the primary, installation path. For everyday use, connect one of the clients in A–C above. The Phase 5A MCP Inspector Validation Runbook documents a fuller Inspector procedure; its paid-exposed surface and resource counts were correct when written for the Phase 4-era three-tool surface and remain accurate history, but the current counts are documented in this README.
Paid tools are disabled by default. Nothing in this section is required to install, inspect, or use the server in default/free mode. This section explains how the paid ST-IM tools are exposed and, separately, how paid execution is gated. Read it before configuring any paid variable. Paid-mode posture is governed by docs/SECURITY_MODEL.md and docs/PHASE5A_OPERATIONAL_HARDENING_DESIGN_MEMO.md.
Paid tool exposure and paid execution are two separate gates. Enabling exposure never, by itself, performs a paid call.
Paid flag parsing is strict: only the literal string true enables STOCKTRENDS_ENABLE_PAID_TOOLS or STOCKTRENDS_ENABLE_PAID_EXECUTION. The values false, 0, no, and off disable them. Other values such as 1, yes, or on fail startup with invalid_config. The execution flag is named STOCKTRENDS_ENABLE_PAID_EXECUTION; STOCKTRENDS_ALLOW_PAID_EXECUTION is not a recognized variable and setting it does nothing.
Paid tool exposure requires both of:
STOCKTRENDS_ENABLE_PAID_TOOLS=trueSTOCKTRENDS_API_KEY configuredWith both set, the server additionally registers the two paired paid ST-IM tool definitions, the two paired paid indicators tool definitions, the base selections tool definition, and the four market-context tool definitions, so the exposed tool set becomes exactly ten:
stocktrends_estimate_workflow_cost — the credential-free planning tool (always present)stocktrends_get_stim_latest — paid ST-IM tool definitionstocktrends_get_stim_history — paid ST-IM tool definitionstocktrends_get_indicators_latest — paid indicators tool definitionstocktrends_get_indicators_history — paid indicators tool definitionstocktrends_get_selections_latest — paid base ST-IM selection universe tool definitionstocktrends_get_market_regime_latest — paid market-context tool definition (regime)stocktrends_get_market_regime_history — paid market-context tool definition (regime)stocktrends_get_breadth_sector_latest — paid market-context tool definition (breadth)stocktrends_get_leadership_summary_latest — paid market-context tool definition (leadership)Exposure does not change what the free planning tool does, and it does not send any API key. It only makes the nine paid tool definitions visible to the MCP client. The internal instrument resolver adds no public tool: it is a credential-free helper used before the paid boundary, so the default/free surface stays at exactly one tool.
Paid execution additionally requires all of:
STOCKTRENDS_ENABLE_PAID_EXECUTION=true — a distinct runtime flag from the exposure flag.STOCKTRENDS_REQUIRE_PRICING_PREFLIGHT stays true).STOCKTRENDS_MAX_PAID_CALLS_PER_SESSION and STOCKTRENDS_MAX_PAID_CALLS_PER_TOOL).STOCKTRENDS_MAX_STC_PER_SESSION, plus STOCKTRENDS_MAX_USD_PER_SESSION where a USD cost applies).Enabling execution changes call behavior, not tool count. When execution is enabled and every gate passes, invoking a paid ST-IM, indicators, selections, or market-context tool may send one authorized request; when it is not enabled, or any resolution/limit/cap/preflight gate fails, the same tool fails closed with no request and no auth header.
The paid surface remains exactly ten tools in every configuration — stocktrends_estimate_workflow_cost, stocktrends_get_stim_latest, stocktrends_get_stim_history, stocktrends_get_indicators_latest, stocktrends_get_indicators_history, stocktrends_get_selections_latest, stocktrends_get_market_regime_latest, stocktrends_get_market_regime_history, stocktrends_get_breadth_sector_latest, and stocktrends_get_leadership_summary_latest. The exposure and execution flags change visibility and behavior, never the tool count.
| Concept | Meaning |
|---|---|
| Exposure | The nine paid tool definitions (stocktrends_get_stim_latest, stocktrends_get_stim_history, stocktrends_get_indicators_latest, stocktrends_get_indicators_history, stocktrends_get_selections_latest, stocktrends_get_market_regime_latest, stocktrends_get_market_regime_history, stocktrends_get_breadth_sector_latest, stocktrends_get_leadership_summary_latest) are visible to the MCP client. |
| Execution | An actual authorized API request may be sent to the approved ST-IM, indicators, base-selections, or market-context endpoint when a paid tool is invoked and its gates pass (ST-IM/indicators additionally require a resolved canonical instrument identity; selections and market-context additionally enforce bounded always-sent limits). |
X-API-Key is attached, and a deterministic secret-free denial is returned.stocktrends_estimate_workflow_cost remain credential-free in every mode. They never send an API key and are unaffected by the exposure or execution flags.The example below exposes the paid tool definitions so an operator can confirm the ten-tool surface. It is for tool exposure only: it does not enable paid execution and must not be used to perform a live paid call.
PowerShell equivalent (Windows):
When the session is over, clear these variables rather than leaving them set:
To confirm no STOCKTRENDS_* variable remains set in the parent shell, without ever printing a value (names only):
Never use setx or a system/user persistent environment variable for any paid variable, especially STOCKTRENDS_API_KEY. setx writes to the Windows registry and persists across every future shell and reboot, defeating per-session credential hygiene; prefer the per-session $env:/export forms above and clear them when the session ends.
With this configuration the MCP client lists exactly ten tools. No paid request is sent, because the execution flag is false and no nonzero caps or budget cap are configured. This is enough to verify the paid exposure surface without any spend. A step-by-step procedure for confirming the paid-exposed surface under MCP Inspector — still without any live paid execution — is documented in the Phase 5A MCP Inspector Validation Runbook (its counts reflect the Phase 4-era three-tool surface; current counts are documented in this README).
Paid execution requires the additional gates described above (execution flag, mandatory preflight, explicit nonzero caps, and a covering budget cap). A step-by-step live-execution runbook is intentionally not included here. For the operator-facing preconditions that must hold before any separately authorized live run — framed conceptually, with no live call commands — see the Phase 5A Operator Safety and Release Checklist. Do not enable paid execution merely to test installation — installation and tool-listing verification are fully demonstrable in free mode and in paid-exposed mode without execution.
PR #69 wires the PR #66 mock challenge helper through the existing nine paid semantic tool names. The x402 relay remains default-off and mock-only. It adds no new tool names, prompts, or resources; sends no network or resolver request; uses no API key; accepts or forwards no proof; constructs no payment header; returns no paid API data; and creates no payment or spend.
With STOCKTRENDS_ENABLE_X402_RELAY=true, the server lists the same ten-tool
shape as API-key paid exposure: the public planning tool plus the existing nine
paid semantic tools. When the challenge-execution flag is absent/off, those
nine invocations fail closed locally with x402_challenge_unavailable. When
both relay and challenge execution are literal true, each paid semantic tool
returns deterministic local, shape-only payment_required metadata. The four
symbol-dependent tools require canonical symbol_exchange in this mode so no
instrument lookup or resolve path can run. An identical repeated challenge call
in one server session fails closed with x402_repeated_challenge_call.
The x402 flags are STOCKTRENDS_ENABLE_X402_RELAY,
STOCKTRENDS_ENABLE_X402_CHALLENGE_EXECUTION, and
STOCKTRENDS_ENABLE_X402_LIVE_CHALLENGE_RELAY, plus the unsupported
STOCKTRENDS_ENABLE_X402_PROOF_FORWARDING. All default to off. Only literal
true enables the first two flags; false, 0, no, and off disable them;
ambiguous truthy values such as 1, yes, or on fail startup with
invalid_config. Proof forwarding is not supported in this build:
setting STOCKTRENDS_ENABLE_X402_PROOF_FORWARDING=true fails closed. Active
x402 relay configuration cannot be combined with
STOCKTRENDS_ENABLE_PAID_TOOLS; mixed mode fails startup before any API-key
read. There is no fallback between x402 and API-key mode.
The live flag also uses strict literal-true parsing and requires both relay
and challenge flags to be literal true; otherwise startup fails with
invalid_config / x402_live_challenge_not_enabled. When all three gates are
true, an allowlisted semantic tool invocation may make exactly one no-key
GET to its corresponding Stock Trends API route after canonical-input,
proof, repeat, per-tool, and per-session gates pass. The request uses the
reviewed API origin, manual redirects, omitted credentials, no body, and only
safe Accept/User-Agent headers. It sends no API key, authorization header,
payment header, proof, or cookie and performs no resolver, catalog, resource,
retry, or fallback call.
Live results return approved status/route/method, header-name, top-level-key,
and field-category metadata only. Conditional challenge values, including the
x-request-id value, are omitted from both structuredContent and text. The
session reserves at most one live challenge per tool and three total; a
reservation remains consumed after network, status, or shape failure to prevent
retry loops. State is in-memory and resets on server restart.
See the Phase 5F x402 Public Mock Wiring Implementation Notes and Phase 5F x402 Live No-Key Challenge Implementation Notes.
These rules apply to every example, screenshot, recording, and shared artifact involving this server.
<your-api-key>).stocktrends_estimate_workflow_cost planning tool never send an API key. They are credential-free regardless of paid configuration.export STOCKTRENDS_API_KEY=<your-api-key> in a single shell) over writing a key into a persistent, machine-wide, or committed location for local inspection.X-API-Key header to the approved paid ST-IM, indicators, base selections/latest, and market-context (market/regime/latest, market/regime/history, breadth/sector/latest, leadership/summary/latest) endpoints, and only after every gate passes. The credential-free instrument resolver (/v1/instruments/lookup, /v1/instruments/resolve), the pricing catalog, and the stocktrends://leadership/definitions public resource never receive it. There is no Authorization: Bearer fallback.Before a release, run the manual secret-safety scan in the Phase 5A Operator Safety and Release Checklist to confirm no real key, populated auth header, or secret-bearing artifact was committed. Placeholders like <your-api-key> are allowed; real-looking secrets are not.
This repository implements a conservative local stdio MCP server for public-resource access, one public/free workflow cost-estimate planning tool, an internal auth/spend-control/pricing-preflight foundation, and the paired paid ST-IM tools with gated live subscription/API-key execution.
Included:
stocktrends_estimate_workflow_cost.stocktrends_get_stim_latest, stocktrends_get_stim_history), paired paid indicators tools (stocktrends_get_indicators_latest, stocktrends_get_indicators_history), the base ST-IM selection-universe tool (stocktrends_get_selections_latest), and the four market-context tools (stocktrends_get_market_regime_latest, stocktrends_get_market_regime_history, stocktrends_get_breadth_sector_latest, stocktrends_get_leadership_summary_latest), exposed only when paid mode is explicitly enabled with an API key (paid-exposed surface = ten tools). Live subscription/API-key execution (X-API-Key only) runs only behind the two-gate policy — the paid-tools flag, an API key, the distinct STOCKTRENDS_ENABLE_PAID_EXECUTION runtime flag, authoritative static pricing/preflight, family-scoped catalog reconciliation, and nonzero local caps (plus a covering budget) — and, for indicators, only after a bare/raw symbol has resolved credential-free to a single canonical identity, and, for selections and market-context, under list-shaped broad-sweep/limit-safety controls (always-sent bounded limits, one fetch, no bulk/retry, repeated-identical-call loop denial); otherwise it fails closed with no request and no auth/payment header. See the Conditional Paid ST-IM Tools, Conditional Paid Indicators Tools, Conditional Paid Selections Tool, and Conditional Paid Market-Context Tools sections.X-API-Key-only auth construction, redaction, static endpoint pricing policy, in-memory per-session spend caps, single-attempt fetch with no retries, and mock-only validation.Excluded:
Authorization: Bearer fallback./v1/ai/tools or /v1/workflows.Work in a dedicated branch or worktree. Do not modify main directly.
Never store API keys, bearer tokens, payment headers, wallet material, database credentials, or other secrets in this repository.
Install dependencies:
Run validation:
Start the built stdio MCP server:
For local TypeScript execution during development:
Do not run the stdio server directly in a terminal expecting human-readable output. stdout is reserved for MCP JSON-RPC messages.
All variables are optional; defaults keep the server in free mode. The Affects column shows whether a variable applies to all modes, to paid tool exposure, or to paid execution (see Paid Mode Configuration). Only STOCKTRENDS_API_KEY is a secret.
| Variable | Affects | Default | Behavior & secret-safety notes |
|---|---|---|---|
STOCKTRENDS_API_BASE_URL | All modes | https://api.stocktrends.com | Must be an approved Stock Trends HTTPS origin. Not a secret. |
STOCKTRENDS_MCP_TRANSPORT | All modes | stdio | Only stdio is supported. Not a secret. |
STOCKTRENDS_MCP_LOG_LEVEL | All modes | warn | Normal logs go to stderr, never stdout. Not a secret. |
STOCKTRENDS_ENABLE_PAID_TOOLS | Paid tool exposure | false | Exposure flag. When true with a configured API key, exposes the two paired paid ST-IM tool definitions, the two paired paid indicators tool definitions, the base selections tool definition, and the four market-context tool definitions (total tools become 10; the internal instrument resolver adds no public tool). Never executes on its own — execution additionally requires STOCKTRENDS_ENABLE_PAID_EXECUTION. Not a secret. |
STOCKTRENDS_API_KEY | Paid exposure + execution | None | Secret — use a placeholder (<your-api-key>) in all docs, examples, screenshots, and shared artifacts; never commit or paste a real value. Read only when STOCKTRENDS_ENABLE_PAID_TOOLS=true; kept process-local. Sent only as the X-API-Key header to the approved origin + allowlisted paid ST-IM, indicators, base selections/latest, and market-context endpoints after every gate passes (no Authorization: Bearer fallback). Never sent for public resources (including stocktrends://leadership/definitions), the cost-estimate planning tool, the pricing catalog, or the credential-free instrument resolver; never logged or exposed in errors/denials/returned data. |
STOCKTRENDS_ENABLE_PAID_EXECUTION | Paid execution | false | Execution flag, distinct from the exposure flag. Live subscription/API-key calls to GET /v1/stim/latest, GET /v1/stim/history, GET /v1/indicators/latest, GET /v1/indicators/history, GET /v1/selections/latest, GET /v1/market/regime/latest, GET /v1/market/regime/history, GET /v1/breadth/sector/latest, and GET /v1/leadership/summary/latest require this to be true and the paid-tools flag, an API key, authoritative static pricing/preflight, family-scoped catalog reconciliation, and ≥1 nonzero call cap plus a budget cap covering the nonzero cost (indicators additionally require a safe resolved canonical identity; selections and market-context additionally enforce bounded always-sent limits and repeated-identical-call loop safety). The flag alone (no tools flag / no key) exposes and executes nothing. Not a secret. |
STOCKTRENDS_ENABLE_X402_RELAY | x402 tool exposure | false | Only literal true exposes the existing nine paid semantic tool names without an API key (ten tools total with the planning tool). false, 0, no, and off disable it; ambiguous truthy values fail startup. Invocations fail closed unless the challenge flag is also enabled. Cannot be mixed with STOCKTRENDS_ENABLE_PAID_TOOLS. Not a secret. |
STOCKTRENDS_ENABLE_X402_CHALLENGE_EXECUTION | x402 challenge behavior | false | Only usable with STOCKTRENDS_ENABLE_X402_RELAY=true. Literal true preserves deterministic local PR #64 shape-only mock results unless the distinct live flag is also true. It performs no resolver lookup, auth, proof, payment, or spend. Not a secret. |
STOCKTRENDS_ENABLE_X402_LIVE_CHALLENGE_RELAY | Live no-key challenge request | false | Only literal true enables; requires both relay and challenge flags to be literal true, otherwise startup fails x402_live_challenge_not_enabled. Allows at most one no-key GET to the exact allowlisted route per accepted invocation, capped at one per tool and three total per server session. Manual redirects, omitted credentials, no body, no API key/auth/payment/proof header, no resolver/catalog/resource side call, no retry/fallback, no paid data, payment, or spend. Conditional challenge values are omitted. Not a secret. |
STOCKTRENDS_ENABLE_X402_PROOF_FORWARDING | Unsupported x402 proof forwarding | false | Proof forwarding remains unsupported. Off values are accepted; true fails startup with invalid_config / proof-forwarding-not-enabled posture. No proof schema, storage, forwarding, payment header, or verification is added. Not a secret. |
STOCKTRENDS_REQUIRE_PRICING_PREFLIGHT | Paid execution | true | Pricing/preflight posture. Preflight is mandatory; setting this false denies paid execution (fail closed) rather than weakening the requirement. Not a secret. |
STOCKTRENDS_MAX_PAID_CALLS_PER_SESSION | Paid execution | 0 | Per-session paid-call cap. 0 denies all paid calls; live execution requires an explicit nonzero value. In-memory per session; resets on restart. Not a secret. |
STOCKTRENDS_MAX_PAID_CALLS_PER_TOOL | Paid execution | 0 | Per-tool paid-call cap. 0 denies; requires an explicit nonzero value. In-memory per session; resets on restart. Not a secret. |
STOCKTRENDS_MAX_STC_PER_SESSION | Paid execution | None | STC budget cap. A nonzero STC cost with no STC cap is denied. Because ST-IM rules are nonzero, a budget cap is effectively mandatory. Not a secret. |
STOCKTRENDS_MAX_USD_PER_SESSION | Paid execution | None | USD budget cap. A nonzero USD cost with no USD cap is denied. Not a secret. |
The server registers these resources:
| MCP resource URI | Backing endpoint |
|---|---|
stocktrends://api/openapi | GET /v1/openapi.json |
stocktrends://ai/context | GET /v1/ai/context |
stocktrends://ai/tools | GET /v1/ai/tools |
stocktrends://workflows | GET /v1/workflows |
stocktrends://methodology/stim | GET /v1/meta/stim |
stocktrends://methodology/indicators | GET /v1/meta/indicators |
stocktrends://methodology/inference | GET /v1/meta/inference |
stocktrends://pricing/catalog | GET /v1/pricing/catalog |
stocktrends://proof/market-edge | GET /v1/ai/proof/market-edge |
stocktrends://leadership/definitions | GET /v1/leadership/definitions |
All ten resources are credential-free in every mode (fetch-on-request, no API key ever). stocktrends://leadership/definitions serves the leadership indicator and taxonomy definitions (verified public/zero-cost by a credential-free read) and is the interpretive companion to the paid leadership summary tool; it is never keyed, never on the paid allowlist, and never mirrored as a paid pricing rule.
Candidate intelligence resources remain excluded until no-key public verification succeeds:
| Excluded candidate endpoint | Reason |
|---|---|
GET /v1/intelligence/discovery | No-key verification returned 503 application/json during Phase 1 and Phase 2 checks on 2026-07-07. |
GET /v1/intelligence/editorial/latest/preview | No-key verification returned 503 application/json during Phase 1 and Phase 2 checks on 2026-07-07. |
The server registers one public/free MCP planning tool:
| MCP tool | Backing endpoint | Purpose |
|---|---|---|
stocktrends_estimate_workflow_cost | GET /v1/cost-estimate | Estimate workflow-level cost for budgeting/planning before paid execution. |
This tool sends no API key or auth header, does not call paid endpoints, does not call /v1/pricing/catalog, does not authorize paid execution or payment, and does not implement x402, wallet, OAuth, remote MCP, database, or control-plane behavior.
When STOCKTRENDS_ENABLE_PAID_TOOLS=true and STOCKTRENDS_API_KEY is configured, the server additionally registers the paired paid ST-IM tool definitions, the paired paid indicators tool definitions, the base selections tool definition, and the four market-context tool definitions (total tools become 10; see Paid Mode Configuration). Otherwise only the public planning tool is registered. Exposure is independent of the execution flag.
| MCP tool | Endpoint | Execution |
|---|---|---|
stocktrends_get_stim_latest | GET /v1/stim/latest | Live subscription/API-key call only when all gates pass; otherwise fails closed. |
stocktrends_get_stim_history | GET /v1/stim/history | Live subscription/API-key call only when all gates pass; otherwise fails closed. |
These two tools are always registered together (history-beside-latest rule). Every invocation validates input strictly (symbol identity with symbol_exchange precedence, exchange in N,Q,A,B,T,I, history date/limit bounds 1–2600) before any preflight, auth, or fetch. A live call occurs only when STOCKTRENDS_ENABLE_PAID_EXECUTION=true, an API key is configured, authoritative static pricing/preflight resolves, the static pricing mirror is reconciled against the live /v1/pricing/catalog metadata (a credential-free read; static pricing alone cannot authorize a call, and a mismatch/unavailability fails closed), and nonzero local caps (plus a budget cap covering the nonzero cost) pass — then exactly one GET is sent with X-API-Key only (no Authorization: Bearer, no payment header, no automatic retries, no x402). The credential-bearing boundary is narrowed to the nine approved paid endpoints only (/v1/stim/latest, /v1/stim/history, /v1/indicators/latest, /v1/indicators/history, /v1/selections/latest, /v1/market/regime/latest, /v1/market/regime/history, /v1/breadth/sector/latest, /v1/leadership/summary/latest); the public instrument-discovery routes (/v1/instruments/lookup, /v1/instruments/resolve), the credential-free /v1/leadership/definitions resource route, the deferred selections routes (/v1/selections/history, /v1/selections/published/*), the deferred market-context routes (/v1/market/regime/forecast, /v1/breadth/sector/history, /v1/leadership/rotation/history), and any other non-promoted endpoint can never receive an X-API-Key. The symbol identity is sent to the API in hyphen form (SYMBOL-EXCHANGE); the underscore canonical form is never forwarded. Successful responses are wrapped with transparent MCP metadata (paid_execution_authorized: true, api_request_sent: true, auth_header_sent: true, payment_header_sent: false, observed_cost: null, payment_status: null) and preserve the API payload verbatim in api_data. Any gate failure returns a deterministic, secret-free denial with paid_execution_authorized: false and no request/auth/payment header. Automated validation is mock-only; no live API call runs in tests. See the Phase 4 Paid ST-IM Live Execution (Subscription) Implementation Notes and docs/SECURITY_MODEL.md §15.
When paid tools are enabled with an API key, the server also registers the paired paid indicators tool definitions alongside the ST-IM pair (contributing to the exactly-ten-tool paid-exposed surface described in Paid Mode Configuration). They are always registered together (history-beside-latest rule) and behave exactly like the ST-IM pair, with one addition: an internal, credential-free instrument resolver runs before any paid boundary.
| MCP tool | Endpoint | Execution |
|---|---|---|
stocktrends_get_indicators_latest | GET /v1/indicators/latest | Live subscription/API-key call only when a safe canonical identity resolves and all gates pass; otherwise fails closed. |
stocktrends_get_indicators_history | GET /v1/indicators/history | Live subscription/API-key call only when a safe canonical identity resolves and all gates pass; otherwise fails closed. |
Inputs accept a canonical symbol_exchange (underscore form, e.g. IBM_N), an explicit symbol + exchange (exchange in N,Q,A,B,T,I), or a bare raw symbol, plus optional cs_only and — for history — start/end and limit (1–2600, API default 260 when omitted). Identity is resolved credential-free before any paid boundary:
symbol_exchange is trusted directly (no discovery call) and sent to the API in hyphen form (IBM-N).symbol + exchange is verified via GET /v1/instruments/resolve using an explicit prefer_exchange equal to the supplied exchange — never the default N.symbol is disambiguated via GET /v1/instruments/lookup: exactly one match resolves credential-free; more than one match fails closed with the candidate symbol_exchange matches and makes no paid call. The resolver deliberately does not rely on /v1/instruments/resolve's default prefer_exchange=N for bare symbols, so the server never silently picks an exchange on your behalf.Only after a single safe canonical identity exists does the tool run the same paid gates as ST-IM — authoritative static pricing (family-specific mirror: indicators_latest_paid 0.0035 STC, indicators_history_paid 0.01 STC), a credential-free reconciliation of that mirror against the live /v1/pricing/catalog metadata (static pricing alone never authorizes a call; a mismatch/unavailability fails closed), nonzero local caps, and the execution flag — then sends exactly one GET with X-API-Key only (no Authorization: Bearer, no payment header, no automatic retries, no x402). The instrument-discovery and catalog reads never receive the API key. The instrument resolver is internal-only: it adds no public MCP tool, so the default/free surface stays at exactly one tool. Successful responses preserve the API payload verbatim in api_data and add mcp_metadata including instrument_resolution (and, on ambiguity, candidate_matches); observed_cost/payment_status remain null and are never fabricated. Automated validation is mock-only; no live API call runs in tests. See the Phase 5B Indicators Implementation Notes.
When paid tools are enabled with an API key, the server also registers a single base ST-IM selection-universe tool alongside the ST-IM and indicators pairs (contributing to the exactly-ten-tool paid-exposed surface described in Paid Mode Configuration). It behaves like the other paid tools with the same gate policy, plus list-shaped broad-sweep/limit-safety controls because it returns a universe/list rather than a single row. It is exchange-scoped, not symbol-keyed, so it uses no instrument resolver.
| MCP tool | Endpoint | Execution |
|---|---|---|
stocktrends_get_selections_latest | GET /v1/selections/latest | Live subscription/API-key call only when all gates pass and the limit is bounded; otherwise fails closed. |
This tool surfaces the base ST-IM selection universe (ranked by prob13wk by the API). It is not the strict published STIM Select list — that is a separate endpoint (/v1/selections/published/latest) that applies published thresholds. This tool never presents base rows as the published list, never applies published thresholds locally, and never ranks, thresholds, scores, filters, or otherwise recomputes rows locally; mcp_metadata carries base-universe provenance so the two surfaces cannot be conflated. No selections/history, selections/published/*, or public selections resource is added this increment.
Inputs (all optional, strict schema, unknown keys rejected): exchange (one of N,Q,A,B,T,I), min_prob13wk (0–1), limit (integer 1–250, default 50), include_data (default false), include_mast (default false), and cs_only (default true). min_prob13wk, exchange, cs_only, and the include_* flags are passed through to the API only and never applied locally.
Broad-sweep / limit safety (far tighter than the API's own 2000 default / 20000 max):
limit is always sent (default 50); the API's 2000 default can never apply. The hard maximum is 250; a limit above 250, below 1, non-integer, an array, or any sentinel fails closed before any pricing/auth/fetch — never silently clamped. There is no all-rows/universe-sweep mode.GET per invocation — no pagination, offset walking, auto-iteration across exchanges, bulk assembly, background refresh, or automatic retry on 429/5xx (fail closed).STOCKTRENDS_MAX_STC_PER_SESSION is required for the 0.05 STC cost. Repeated identical base selection calls within a session fail closed (repeated_identical_selection_call) rather than silently re-billing.Pricing is a fresh, selections-family static mirror (selections_latest_paid 0.05 STC) reconciled credential-free and family-scoped against the live /v1/pricing/catalog metadata (missing/duplicate rule, cost mismatch, or missing/unsupported/conflicting STC unit fails closed; an ST-IM/indicators/published mirror never satisfies it). When every gate passes, exactly one GET is sent with X-API-Key only (no Authorization: Bearer, no payment header, no x402, no retries). Successful responses preserve the API payload verbatim in api_data and add mcp_metadata including base-vs-published provenance, effective_limit, and the returned row count; observed_cost/payment_status remain null and are never fabricated. Automated validation is mock-only; no live API call runs in tests. See the Phase 5C Selections/Latest Implementation Notes.
When paid tools are enabled with an API key, the server also registers the four Phase 5D market-context tools alongside the prior families, bringing the paid-exposed surface to exactly ten tools. They behave like the other paid tools with the same gate policy, plus market-context limit-safety controls because the data is weekly-cadence and market-scoped. None of them is symbol-keyed, so no instrument resolver is involved.
| MCP tool | Endpoint | Cost | Limits (always sent) |
|---|---|---|---|
stocktrends_get_market_regime_latest | GET /v1/market/regime/latest | 0.15 STC | — (snapshot; strict empty input, unknown keys rejected) |
stocktrends_get_market_regime_history | GET /v1/market/regime/history | 0.25 STC | limit default 12, hard max 52 (the API's own max); optional start_date (YYYY-MM-DD) passthrough |
stocktrends_get_breadth_sector_latest | GET /v1/breadth/sector/latest | 0.1 STC | limit default 50, hard max 250; group_level default sector always sent |
stocktrends_get_leadership_summary_latest | GET /v1/leadership/summary/latest | 0.25 STC | limit_overall default 50, hard max 200; limit_bucket default 20, hard max 50 |
Context, not advice. These tools forward Stock Trends API-authored market context verbatim and never turn it into a recommendation: a regime label is market context, not a trading recommendation; breadth rows are participation context, not confirmation signals to act on; leadership tables are rotation context, not picks. The adapter performs no local regime calculation, breadth re-aggregation, or leadership re-ranking/re-bucketing/thresholding, and produces no buy/sell/hold/allocation or suitability output.
Additional input policy: exchange (one of N,Q,A,B,T,I), breadth's cs_only/include_unknown/min_price/min_volume, and leadership's min_rsi/min_mt_cnt (0–500) are validated passthroughs sent only when supplied so API defaults apply; none is applied locally. weekdate is deliberately not exposed on either latest tool (no snapshot time-travel that would reconstruct history through a latest route), and vol_scale (unbounded legacy multiplier) and type (no verified enum) are not exposed; all are rejected as unknown keys. Invalid/out-of-range/array/sentinel limits fail closed before any pricing/auth/fetch and are never clamped. Exactly one GET per invocation — no pagination, date-range sweeping, exchange iteration, bulk assembly, or automatic retry — and repeated identical calls (same tool + normalized parameters; the zero-parameter regime-latest signature is constant) fail closed (repeated_identical_market_context_call) rather than re-billing weekly data.
Pricing uses three fresh family-scoped static mirrors (market_regime_latest 0.15 STC and market_regime_history 0.25 STC in family market — the verified rule ids carry no _paid suffix; breadth_sector_latest_paid 0.1 STC in family breadth; leadership_summary_latest_paid 0.25 STC in family leadership), each reconciled credential-free against the live /v1/pricing/catalog metadata with the same fail-closed checks (missing/duplicate rule, endpoint/family/cost/unit mismatch, non-paid classification). The deferred routes /v1/market/regime/forecast, /v1/breadth/sector/history (API default/max 200000/500000 — never reachable through this adapter), and /v1/leadership/rotation/history are not implemented, not promoted, and denied endpoint_not_allowlisted. Successful responses preserve the API payload verbatim in api_data and add mcp_metadata with context-not-advice provenance, effective_limits, the returned row count where derivable, and the API-reported weekdate only when present; observed_cost/payment_status remain null and are never fabricated. Automated validation is mock-only; no live API call runs in tests. See the Phase 5D Market-Context Implementation Notes and docs/SECURITY_MODEL.md §17.