Stocktrends MCP Server

Stock Trends MCP Server

Stock Trends Model Context Protocol (MCP) server for the live public Remote MCP and separately available local stdio clients.

Architecture Boundary (What This Server Is)

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.

Public Remote MCP

Connect a remote MCP client to the Streamable HTTP endpoint:

https://mcp.stocktrends.com/mcp

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.

Local stdio and Streamable HTTP configuration

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:

Stock Trends dataset
  -> Stock Trends API
  -> published Stock Trends API responses/artifacts
  -> MCP adapter (this repository)
  -> external MCP clients/agents

The MCP adapter:

• Does not recompute Stock Trends data, ST-IM, or indicators.
• Does not access the Stock Trends database or control plane directly.
• Does not generate investment advice, research, or trading guidance.
• Only translates reviewed, published Stock Trends API responses into MCP resource and tool responses.

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.

Default / Free Mode Quickstart

This is the recommended first path for installing or inspecting the server. In default mode, the server:

• Requires no API key.
• Performs no paid execution and creates no spend.
• Exposes three free MCP tools: stocktrends_estimate_workflow_cost, stocktrends_lookup_instruments, and stocktrends_resolve_instrument.
• Makes all public resources available credential-free.
• Registers zero MCP prompts.

Setup

Using only the existing project scripts:

git clone <repository-url>
cd stocktrends-mcp-server
npm install
npm run build

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.

Public npm Installation

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:

npm install @stocktrends-publications/stocktrends-mcp-server

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.

Local Package Artifact Installation (build-it-yourself alternative)

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.

• The artifact is not retained in this repository — no .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 use this path, build the artifact yourself from a reviewed checkout.

To build the local artifact yourself from a checkout:

git clone <repository-url>
cd stocktrends-mcp-server
npm install
npm run build
npm pack

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):

npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>

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.

Inspect with MCP Inspector (no API key)

After building (npm run build), point the MCP Inspector at the compiled stdio server, with no paid-mode environment variables set:

npx @modelcontextprotocol/inspector node dist/server.js

In the Inspector UI, confirm:

• The tool list contains exactly the three free tools 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.
• The prompts list is empty, if the client exposes a prompts panel.
• Public resources (for example 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).

Secret Safety (free mode)

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.

Connect a local stdio MCP client

This section wires the server into an MCP client over local stdio. Two installation shapes are covered, clearly separated in each subsection below:

• Repository-checkout path (build first with 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.
• Local-package-artifact path (see Local Package Artifact Installation above): launches the npm-installed command shim resolved from <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.

A. Claude Desktop

Free-mode mcpServers entry (no env block — credential-free by default):

{
  "mcpServers": {
    "stocktrends": {
      "command": "node",
      "args": ["<absolute-path-to-checkout>/dist/server.js"]
    }
  }
}

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:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Verify 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:

{
  "mcpServers": {
    "stocktrends": {
      "command": "<path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server"
    }
  }
}

Windows equivalent (the generated .cmd shim):

{
  "mcpServers": {
    "stocktrends": {
      "command": "<path-to-consumer-project>\\node_modules\\.bin\\stocktrends-mcp-server.cmd"
    }
  }
}

<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:

{
  "mcpServers": {
    "stocktrends": {
      "command": "node",
      "args": ["<absolute-path-to-checkout>/dist/server.js"],
      "env": {
        "STOCKTRENDS_ENABLE_PAID_TOOLS": "true",
        "STOCKTRENDS_API_KEY": "<your-api-key>"
      }
    }
  }
}

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.

B. Claude Code

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:

claude mcp add --transport stdio stocktrends -- node <absolute-path-to-checkout>/dist/server.js

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):

{
  "mcpServers": {
    "stocktrends": {
      "command": "node",
      "args": ["<absolute-path-to-checkout>/dist/server.js"]
    }
  }
}

Package-installed variant (local artifact path, free mode, POSIX):

claude mcp add --transport stdio stocktrends -- <path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server

Package-installed variant (local artifact path, free mode, Windows):

claude mcp add --transport stdio stocktrends -- <path-to-consumer-project>\node_modules\.bin\stocktrends-mcp-server.cmd

<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.

C. Generic MCP stdio client

Any MCP client that supports local stdio servers can use this client-agnostic shape:

{
  "command": "node",
  "args": ["<absolute-path-to-checkout>/dist/server.js"],
  "env": {}
}

Package-installed variant (local artifact path, free mode). POSIX:

{
  "command": "<path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server",
  "env": {}
}

Windows (the generated .cmd shim):

{
  "command": "<path-to-consumer-project>\\node_modules\\.bin\\stocktrends-mcp-server.cmd",
  "env": {}
}

<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):

{
  "command": "node",
  "args": ["<absolute-path-to-checkout>/dist/server.js"],
  "env": {
    "STOCKTRENDS_ENABLE_PAID_TOOLS": "true",
    "STOCKTRENDS_API_KEY": "<your-api-key>"
  }
}

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.

D. MCP Inspector as diagnostic reference

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 Mode Configuration

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=true
• STOCKTRENDS_API_KEY configured

With 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 definition
• stocktrends_get_stim_history — paid ST-IM tool definition
• stocktrends_get_indicators_latest — paid indicators tool definition
• stocktrends_get_indicators_history — paid indicators tool definition
• stocktrends_get_selections_latest — paid base ST-IM selection universe tool definition
• stocktrends_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.
• The mandatory pricing preflight resolving (STOCKTRENDS_REQUIRE_PRICING_PREFLIGHT stays true).
• Explicit nonzero local caps (STOCKTRENDS_MAX_PAID_CALLS_PER_SESSION and STOCKTRENDS_MAX_PAID_CALLS_PER_TOOL).
• A budget cap that covers the nonzero cost (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.

Exposure vs Execution

• The execution gate is intentionally stricter than the exposure gate. Making a tool definition visible is deliberately easier than authorizing a real, billable call.
• If execution is not enabled, or the caps / pricing preflight fail, the paid tools fail closed: no request is sent, no X-API-Key is attached, and a deterministic secret-free denial is returned.
• Public resources and 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.

Enable paid tool exposure (exposure only — no execution)

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.

# 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=true
export 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

PowerShell equivalent (Windows):

# 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"

When the session is over, clear these variables rather than leaving them set:

# POSIX
unset STOCKTRENDS_ENABLE_PAID_TOOLS STOCKTRENDS_API_KEY STOCKTRENDS_ENABLE_PAID_EXECUTION

# PowerShell
Remove-Item Env:STOCKTRENDS_ENABLE_PAID_TOOLS -ErrorAction SilentlyContinue
Remove-Item Env:STOCKTRENDS_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:STOCKTRENDS_ENABLE_PAID_EXECUTION -ErrorAction SilentlyContinue

To confirm no STOCKTRENDS_* variable remains set in the parent shell, without ever printing a value (names only):

# PowerShell — names only, never values
Get-ChildItem Env: | Where-Object { $_.Name -like 'STOCKTRENDS_*' } | Select-Object -ExpandProperty Name

# POSIX — names only, never values
env | grep '^STOCKTRENDS_' | cut -d= -f1

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.

x402 challenge relay flags

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.

Secret Safety

These rules apply to every example, screenshot, recording, and shared artifact involving this server.

• Never commit API keys. No key belongs in this repository, a checked-in config, or any committed file.
• Never paste a real API key into README examples, screenshots, terminal recordings, shared chats, or issue reports. Use placeholders only (for example <your-api-key>).
• Free/default mode needs no key. It is fully functional with no API key, and the quickstart must be demonstrated without one.
• Public resources and the stocktrends_estimate_workflow_cost planning tool never send an API key. They are credential-free regardless of paid configuration.
• Prefer per-session shell environment variables (for example 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.
• The API key, when paid tools are enabled, is sent only as the 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.
• The key is never logged and never appears in errors, denials, or returned data.

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.

Current Status

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:

Documentation truncated — see the full README on GitHub.