Stock Trends MCP

When to use MCP instead of calling the REST API directly

MCP and the REST API deliver the same Stock Trends intelligence. They differ in how the intelligence reaches the caller.

• Tool-shaped, not route-shaped. Capabilities arrive as named tools and resources with typed input schemas, so an agent environment can list and invoke them without a hand-written client.
• Discovery before spend. The discovery, methodology, pricing, and proof resources are credential-free. An agent can understand the service and estimate workflow cost before any premium call is configured.
• Explicit spend boundaries. Paid tools are off by default. Exposure and execution are separate flags, and live calls additionally require pricing reconciliation and non-zero local call and budget caps.
• Build a service? Use the REST API. Applications, backend services, scheduled jobs, and trading systems should integrate the REST API directly. MCP is for interactive and agentic environments that speak the protocol.

How MCP relates to the Stock Trends API

1. Source

   Stock Trends classification framework

   Weekly market observations encoded by one consistent classification doctrine, as described on the home page and the Evidence & Validation page.

2. Contract

   Stock Trends API

   The authoritative intelligence contract: endpoint behaviour, request schemas, response fields, pricing, and payment requirements. Documented by the OpenAPI schema.

3. Adapter

   Stock Trends MCP server

   A local stdio process that fetches published API responses on request and returns them as MCP resources and tool results, with provenance metadata attached and the API payload preserved verbatim.

4. Consumer

   MCP-compatible agent

   Any agent environment that can launch a local stdio MCP server.

The API defines the intelligence contract. MCP makes that intelligence easier for compatible agents to discover and invoke as tools.

What the MCP server exposes

Credential-free resources

Ten MCP resources are fetched on request and never send an API key, in any configuration. They cover discovery, methodology, pricing, and evidence.

Free planning tool

One MCP tool is registered in every configuration, sends no credential, and performs no paid execution.

Paid tools — disabled by default

Nine paid tools are registered only when paid mode is explicitly enabled with a subscription API key. They are not present in the default configuration.

Access for these endpoints: Subscription · x402 · MPP at the API. Through the MCP adapter, only subscription execution is implemented — see payment and access behaviour. Check GET /v1/pricing/catalog for current per-endpoint pricing before execution.

The base selection-universe tool returns the ST-IM selection universe ranked by the API. It is not the strict published STIM Select list, which is a separate endpoint. Regime labels are market context rather than trading recommendations, breadth rows are participation context rather than confirmation signals, and leadership tables are rotation context rather than picks. The adapter performs no local ranking, thresholding, or re-aggregation.

Supported connection modes today

The published server supports local stdio only. There is no hosted or remote Stock Trends MCP endpoint at this time.

Verified client environments

Any MCP client that can launch a local stdio server can connect using the generic configuration below. The table records what has actually been observed against this server, so you can tell verification apart from documentation.

What the MCP server does not do

• It does not host a remote endpoint, and it registers zero MCP prompts.
• It does not recompute Stock Trends classifications, ST-IM distributions, indicators, breadth, or leadership.
• It does not access the Stock Trends database or control plane.
• It does not generate investment advice, research, guidance, or trading instructions.
• It does not make payments, hold wallet material, forward payment proof, or send payment headers.
• It does not register tools dynamically from /v1/ai/tools or /v1/workflows; the exposed surface is fixed by the release.

Install and configure

The package is published to the public npm registry. Installing and running it in the default configuration requires no API key, creates no spend, and exposes the credential-free resources plus the single planning tool.

1. Install from npm

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

The package installs an npm-managed command shim in the consumer project at node_modules/.bin/stocktrends-mcp-server (on Windows, node_modules\.bin\stocktrends-mcp-server.cmd). Resolve it from that project rather than assuming a global install. Append @1.0.1 to pin an exact release.

2. Configure your MCP client

Generic MCP stdio client

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

Claude Desktop — add to the mcpServers block:

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

On Windows use the generated .cmd shim and escape backslashes, or use forward slashes — a single backslash is not valid JSON. Verify the config file location against your installed client version.

Claude Code — register the server over stdio:

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

3. Confirm the surface

Point the MCP Inspector at the server, with no Stock Trends environment variables set, and confirm the default boundary:

npx @modelcontextprotocol/inspector <path-to-your-project>/node_modules/.bin/stocktrends-mcp-server

• The tool list contains exactly stocktrends_estimate_workflow_cost.
• The nine paid tools are not visible.
• The prompts list is empty.
• All ten resources are listed and readable with no credential configured.

Building from a repository checkout is also supported: npm install then npm run build, and launch node <checkout>/dist/server.js. See the repository README for the full installation matrix and the current environment-variable reference.

An example agent workflow over MCP

A first session that understands the service and prices the work before any premium execution is configured. Every step below is credential-free.

1. Read stocktrends://ai/tools to discover capability families, supported rails, and the recommended call sequence.
2. Read stocktrends://ai/context to ground terminology — including that Stock Trends RSI is relative performance versus a benchmark with baseline 100, not Wilder RSI.
3. Read stocktrends://workflows to choose a task-level workflow rather than assembling endpoints by hand.
4. Read stocktrends://proof/market-edge and stocktrends://methodology/stim to inspect signal structure and ST-IM assumptions.
5. Read stocktrends://pricing/catalog for live per-endpoint pricing.
6. Call stocktrends_estimate_workflow_cost with the chosen workflow_id to get a workflow-level estimate and an optional local budget comparison.
7. Decide how to execute: enable the paid MCP tools with a subscription key, or call the REST API directly with subscription, x402, or MPP.

The cost-estimate result is planning evidence. It does not authorize paid execution or payment, and the tool reports that explicitly in its metadata.

Payment and access behaviour

The MCP adapter and the REST API do not support the same set of payment rails. This is the part most worth reading before you plan an integration.

If you want autonomous machine payment, call the REST API with a standard x402 V2 client or an MPP funded session. Use MCP for discovery, interpretation, planning, and subscription-backed execution.

Spend controls on the paid tools

Exposure and execution are separate gates. Enabling exposure never performs a paid call on its own. A live subscription call additionally requires that the server's static pricing mirror reconciles against the live pricing catalog, and that non-zero call and budget caps are configured — every cap defaults to zero, which denies.

• Exactly one request per tool invocation. No pagination, bulk assembly, background refresh, or automatic retry.
• Bounded row limits are always sent, well below the API's own maxima.
• Repeated identical calls within a session fail closed rather than re-billing.
• Ambiguous bare symbols fail closed with candidate matches instead of the server picking an exchange for you.
• The API key is sent only as X-API-Key, only to the nine allowlisted paid endpoints, and is never logged or returned.

Paid-mode configuration is an operator-supervised procedure, not a copy-paste recipe. Read the repository README and its security model before setting any paid variable, and never place a real API key in a persistent client configuration file.

Where to inspect the underlying contract

The MCP server is an access surface. For endpoint behaviour, request schemas, response fields, pricing, and payment requirements, the API is authoritative.

• OpenAPI schema — canonical request and response contract
• Interactive API docs
• Canonical API llms.txt — programmatic usage guide
• /v1/ai/tools — machine-readable capability discovery
• /v1/pricing/catalog — live endpoint pricing
• MCP server repository — README, security model, and architecture notes
• npm package — published releases
• MCP Registry entry — com.stocktrends/market-intelligence

Important disclosures

Stock Trends provides structured market context and probabilistic research intelligence. Whether accessed through the REST API or through MCP, its outputs are not investment advice, price targets, direct buy/sell commands, or guarantees of future performance, and they are not a substitute for your own investment process, risk controls, or professional advice.