com.stocktrendsPublished by stocktrends.comOfficial publisherv1.0.2Updated Oct 24, 2026
Equity trend, relative-strength, expected-return, market-context, and research resources for agents.
Stock Trends Market Intelligence gives an assistant free instrument lookup and cost estimation, plus paid, x402-gated equity trend, market-context and portfolio
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/com.stocktrends%2Fmarket-intelligence/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"stock-trends-market-intelligence": {
"type": "http",
"url": "https://mcp.stocktrends.com/mcp"
}
}
}Stock Trends Model Context Protocol (MCP) server for the live public Remote MCP and separately available local stdio clients.
This repository is a thin MCP adapter over the front-facing Stock Trends API. It powers the live public Remote MCP and supports local stdio; it has no independent analytical authority of its own.
Connect a remote MCP client to the Streamable HTTP endpoint:
Developer connection guidance is available at developer.stocktrends.com/mcp. The deployed remote surface exposes exactly 19 tools, ten public resources, and zero prompts. Connection and discovery require no Stock Trends subscription API key. Three tools are free: stocktrends_estimate_workflow_cost, stocktrends_lookup_instruments, and stocktrends_resolve_instrument. Sixteen tools are x402 V2 paid tools: the 12 GET 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, stocktrends_get_screener_top, stocktrends_get_market_epoch_latest, and stocktrends_get_market_epoch_history; and the four POST tools stocktrends_evaluate_symbol (POST /v1/decision/evaluate-symbol), stocktrends_construct_portfolio (POST /v1/portfolio/construct), stocktrends_evaluate_portfolio (POST /v1/portfolio/evaluate), and stocktrends_compare_portfolios (POST /v1/portfolio/compare). stocktrends_get_selections_latest returns the base selection universe, not the separately thresholded published ST-IM Select list.
For the paid remote tools, a payment-capable MCP client obtains and authorizes payment. It supplies that authorization in MCP request metadata as x402/payment; the adapter forwards it to the Stock Trends API in the upstream PAYMENT-SIGNATURE header and returns confirmed settlement metadata as x402/payment-response. These MCP metadata fields are distinct from the API headers. The server does not control a buyer wallet, hold private keys, sign payment authorizations, initiate spending, recompute Stock Trends intelligence, or execute securities trades. A client does not gain payment capability merely by connecting, and a conforming x402 REST buyer does not automatically implement this MCP-specific exchange. Do not automatically retry an uncertain payment outcome; for a POST tool, a settled payment can accompany an analytical HTTP error, and pending challenge state is bound to the adapter's canonical request body rather than independently cryptographically signing that body.
Node.js 20+ is required for local use. Local stdio remains the default transport for local process startup and is fully supported. Source also supports explicit STOCKTRENDS_MCP_TRANSPORT=streamable-http, serving MCP at /mcp and operational checks at /healthz and /readyz; its local listener binds to 127.0.0.1:3000 by default. The deployed public endpoint above is distinct from this local configuration. Official MCP Registry version 1.0.2 is published, active, and latest; it advertises both the local stdio npm package and the Remote MCP endpoint https://mcp.stocktrends.com/mcp over Streamable HTTP.
By default, a locally started streamable-http configuration is credential-free: ten public resources, the three free tools listed above, and no prompts. It refuses a configured API key, paid-tools/execution settings, or the separate local x402 relay/challenge/live/proof-forwarding settings. STOCKTRENDS_ENABLE_REMOTE_X402_STIM=true is the distinct, Streamable HTTP-only activation for the production-style Remote x402 registrations: it exposes the three free tools plus 16 x402-paid tools (19 total), without enabling API-key paid mode or the local challenge relay. This source-level activation is distinct from the deployed public service and is not a deployment guide. Local stdio retains separately gated subscription/API-key paid REST calls. Its optional, default-off x402 mode is challenge metadata inspection/relay only: it neither makes a payment nor forwards payment proof or payment headers, returns paid API data, or spends. MPP is not implemented.
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? For the public Remote MCP, use the endpoint and Developer Portal above. To run a local server, start with the Default / Free Mode Quickstart, then Connect a local stdio MCP client. 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, stocktrends_lookup_instruments, and stocktrends_resolve_instrument.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). The published npm 1.0.1 artifact is likewise a historical one-free-tool release; that published-package result does not describe the current source checkout's three-tool free surface. Official MCP Registry version 1.0.2 for com.stocktrends/market-intelligence is published, active, and latest. It advertises the existing npm 1.0.1 local stdio package and the Remote MCP endpoint https://mcp.stocktrends.com/mcp over Streamable HTTP; the Registry metadata version and npm package version are intentionally distinct.
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, stocktrends_lookup_instruments, and stocktrends_resolve_instrument; the nine local subscription/API-key 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 all three tools are 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 twelve:
stocktrends_estimate_workflow_cost — the credential-free planning tool (always present)stocktrends_lookup_instruments — credential-free instrument-discovery tool (always present)stocktrends_resolve_instrument — credential-free instrument-resolution 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 the three free tools or send any API key. It only makes the nine paid tool definitions visible to the MCP client. The internal instrument resolver used by paid indicators is a credential-free helper; it is distinct from the separately registered public stocktrends_lookup_instruments and stocktrends_resolve_instrument tools. The default/free surface therefore stays at three tools.
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 local subscription/API-key paid surface contains twelve tools when exposure is enabled: the three free tools plus 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 that local paid-surface count.
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 twelve-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 twelve tools: three free tools plus nine local subscription/API-key paid tool definitions. 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 twelve-tool
shape as API-key paid exposure: the three free tools 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 powers the deployed public Remote MCP at https://mcp.stocktrends.com/mcp over Streamable HTTP: 19 tools (three free and 16 x402 V2 paid), ten resources, and zero prompts. The paid remote surface includes 12 GET tools and four analytical POST tools; it uses the MCP-specific x402/payment and x402/payment-response metadata exchange, while forwarding accepted authorization upstream in PAYMENT-SIGNATURE. Local stdio remains the default for local process startup and supports the free/default surface, separately gated subscription/API-key paid tools, and optional default-off x402 challenge inspection/relay only (no payment, proof forwarding, payment header, paid data, or spend).
Included:
stocktrends_estimate_workflow_cost, stocktrends_lookup_instruments, and stocktrends_resolve_instrument.x402/payment; the server forwards it only to the allowlisted Stock Trends API endpoint as PAYMENT-SIGNATURE, reports confirmed settlement through x402/payment-response, and neither holds nor signs with a buyer wallet.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 (three free tools plus nine paid tools = 12 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.
The server registers these resources:
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:
Current source-head local default/free mode registers three public/free MCP tools. The workflow-planning tool is:
This tool sends no API key or auth header, does not call paid endpoints or
/v1/pricing/catalog, does not authorize paid execution or payment, and
implements no x402 payment, wallet, OAuth, database, or control-plane behavior.
The two additional free instrument-discovery tools are also registered in local
default/free mode:
The deployed Remote MCP exposes the same three free tools; see Public Remote MCP.
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 (three free tools plus nine paid tools = 12; see Paid Mode Configuration). Otherwise only the three free tools are registered. Exposure is independent of the execution flag.
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 twelve-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.
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. This paid-indicator resolver is an internal helper, distinct from the two public discovery tools, so the default/free surface remains three tools. 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 twelve-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.
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 local subscription/API-key paid-exposed surface to twelve tools (three free plus nine paid). 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.
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.
Source: README.md at commit b3182c6
Estimate Stock Trends Workflow Cost
Public/free planning tool that calls GET /v1/cost-estimate for workflow-level budgeting only. It does not authorize paid execution, payment, x402, wallet use, or paid endpoint calls.
workflow_idrequiredmax_budget_stcmax_budget_usdquota_remainingrail_preferenceLookup Stock Trends Instruments
Search public instrument candidates across exchanges. It does not select an ambiguous symbol or make a paid request.
limitsymbolrequiredcs_onlydetailsResolve a Stock Trends Instrument
Resolve a Stock Trends instrument identifier. The API prefers U.S. listings by default; specify exchange or canonical symbol_exchange for a particular listing, including Canadian securities. Use lookup to explore alternatives. Upstream 404 and 409 responses are preserved.
symbolcs_onlydetailsexchangeprefer_exchangesymbol_exchangeGet Latest Stock Trends ST-IM Record
Purchase the latest API-authored ST-IM record with an x402 payment authorization. symbol_exchange uses canonical IBM-N form; legacy IBM_N is accepted temporarily.
symbol_exchangerequiredGet Stock Trends ST-IM History
Purchase bounded API-authored ST-IM history with an x402 payment authorization. The API data is probabilistic context, not a forecast or recommendation.
endlimitstartinclude_gapssymbol_exchangerequiredGet Latest Stock Trends Indicators
Purchase the latest API-authored instrument classification with an x402 payment authorization.
cs_onlysymbol_exchangerequiredGet Stock Trends Indicators History
Purchase bounded API-authored instrument classification history with an x402 payment authorization.
endlimitstartcs_onlysymbol_exchangerequiredGet Latest Stock Trends Base Selection Universe
Purchase the API-authored base ST-IM selection universe with an x402 payment authorization. This is not the separately thresholded published STIM Select list.
limitcs_onlyexchangeinclude_datainclude_mastmin_prob13wkGet Latest Stock Trends Market Regime
Purchase the latest API-authored market regime classification with an x402 payment authorization. Regime is market context, not a trading recommendation.
Takes no parameters.
Get Stock Trends Market Regime History
Purchase bounded API-authored market regime history with an x402 payment authorization. Regime is market context, not a forecast or recommendation.
limitstart_dateGet Latest Stock Trends Sector Breadth
Purchase the API-authored sector breadth snapshot with an x402 payment authorization. Breadth is participation context, not a trading recommendation.
limitcs_onlyexchangemin_pricemin_volumegroup_levelinclude_unknownGet Latest Stock Trends Leadership Summary
Purchase the API-authored leadership summary with an x402 payment authorization. Leadership is rotation context, not stock picks.
min_rsimin_mt_cntlimit_bucketlimit_overallGet Top Stock Trends Screener Results
Purchase the API-authored ranked screener output with an x402 payment authorization. Results are research context, not a buy or sell recommendation.
sortlimittrendmin_rsiexchangeweekdatemin_mt_cntmin_trend_cntGet Latest Market Epoch
Purchase the latest persisted Market Epoch v1 structural market-state context. Epoch is descriptive context, not a trade signal, forward-return forecast, probability forecast, or trading recommendation.
Takes no parameters.
Get Market Epoch History
Purchase bounded persisted Market Epoch v1 history. Epoch is descriptive context, not a trade signal, forward-return forecast, probability forecast, or trading recommendation. This tool preserves API-authored snapshots and performs no local Epoch calculation or interpretation.
limitend_datestart_dateEvaluate a Stock Trends Symbol
Purchase API-authored analytical decision context for one instrument. This is research context, not investment advice or a trade instruction.
symbolexchangesymbol_exchangeConstruct a Stock Trends Portfolio
Purchase an API-authored equal-weight analytical allocation proposal. It does not execute trades or manage assets.
biascountexchangeuniverseEvaluate a Stock Trends Portfolio
Purchase the API's analytical assessment of supplied positions. It does not execute trades or manage assets.
positionsrequiredCompare Stock Trends Portfolios
Purchase the API's analytical comparison of two supplied portfolios. It does not execute trades or manage assets.
leftrequiredrightrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
https://mcp.stocktrends.com/mcpStock Trends dataset -> Stock Trends API -> published Stock Trends API responses/artifacts -> MCP adapter (this repository) -> external MCP clients/agentsgit clone <repository-url>cd stocktrends-mcp-servernpm installnpm run buildnpm install @stocktrends-publications/stocktrends-mcp-servergit clone <repository-url>cd stocktrends-mcp-servernpm installnpm run buildnpm packnpm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>npx @modelcontextprotocol/inspector node dist/server.js{ "mcpServers": { "stocktrends": { "command": "node", "args": ["<absolute-path-to-checkout>/dist/server.js"] } }}{ "mcpServers": { "stocktrends": { "command": "<path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server" } }}{ "mcpServers": { "stocktrends": { "command": "<path-to-consumer-project>\\node_modules\\.bin\\stocktrends-mcp-server.cmd" } }}{ "mcpServers": { "stocktrends": { "command": "node", "args": ["<absolute-path-to-checkout>/dist/server.js"], "env": { "STOCKTRENDS_ENABLE_PAID_TOOLS": "true", "STOCKTRENDS_API_KEY": "<your-api-key>" } } }}claude mcp add --transport stdio stocktrends -- node <absolute-path-to-checkout>/dist/server.js{ "mcpServers": { "stocktrends": { "command": "node", "args": ["<absolute-path-to-checkout>/dist/server.js"] } }}claude mcp add --transport stdio stocktrends -- <path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-serverclaude mcp add --transport stdio stocktrends -- <path-to-consumer-project>\node_modules\.bin\stocktrends-mcp-server.cmd{ "command": "node", "args": ["<absolute-path-to-checkout>/dist/server.js"], "env": {}}{ "command": "<path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server", "env": {}}{ "command": "<path-to-consumer-project>\\node_modules\\.bin\\stocktrends-mcp-server.cmd", "env": {}}{ "command": "node", "args": ["<absolute-path-to-checkout>/dist/server.js"], "env": { "STOCKTRENDS_ENABLE_PAID_TOOLS": "true", "STOCKTRENDS_API_KEY": "<your-api-key>" }}# Exposure only: makes the nine paid ST-IM, indicators, base-selections, and# market-context tool definitions visible.# This does NOT authorize or perform any paid API call.export STOCKTRENDS_ENABLE_PAID_TOOLS=trueexport STOCKTRENDS_API_KEY="<your-api-key>" # placeholder — never paste a real key# Execution stays disabled (its default). Do not set this to true just to test exposure.export STOCKTRENDS_ENABLE_PAID_EXECUTION=false# Exposure only: makes the nine paid ST-IM, indicators, base-selections, and# market-context tool definitions visible.# This does NOT authorize or perform any paid API call.$env:STOCKTRENDS_ENABLE_PAID_TOOLS = "true"$env:STOCKTRENDS_API_KEY = "<your-api-key>" # placeholder — never paste a real key# Execution stays disabled (its default). Do not set this to true just to test exposure.$env:STOCKTRENDS_ENABLE_PAID_EXECUTION = "false"# POSIXunset STOCKTRENDS_ENABLE_PAID_TOOLS STOCKTRENDS_API_KEY STOCKTRENDS_ENABLE_PAID_EXECUTION# PowerShellRemove-Item Env:STOCKTRENDS_ENABLE_PAID_TOOLS -ErrorAction SilentlyContinueRemove-Item Env:STOCKTRENDS_API_KEY -ErrorAction SilentlyContinueRemove-Item Env:STOCKTRENDS_ENABLE_PAID_EXECUTION -ErrorAction SilentlyContinue# PowerShell — names only, never valuesGet-ChildItem Env: | Where-Object { $_.Name -like 'STOCKTRENDS_*' } | Select-Object -ExpandProperty Name# POSIX — names only, never valuesenv | grep '^STOCKTRENDS_' | cut -d= -f1npm installnpm run typechecknpm testnpm run buildnpm run buildnpm startnpm run dev