stoploss.ai · mcp server

Documentation

The Stoploss.ai MCP Server gives AI assistants native access to institutional-grade Indian market intelligence — fundamental screening, technical signals, live news sentiment, and quant models — through the standard Model Context Protocol.

Tools

Avg Latency

<200ms

Coverage

NSE + BSE

Quickstart#

The MCP server uses stdio and SSE transports. Pick your client:

Claude Desktop

Edit claude_desktop_config.json (found in your Claude settings → Developer):

json

{
  "mcpServers": {
    "stoploss": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/stoploss-mcp",
        "run",
        "stoploss-mcp"
      ],
      "env": {
        "STOPLOSS_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You will see stoploss connected in the bottom-left toolbar.

Cursor / VS Code

json

// .cursor/mcp.json  (or .vscode/mcp.json)
{
  "mcpServers": {
    "stoploss": {
      "command": "uvx",
      "args": ["stoploss-mcp"],
      "env": {
        "STOPLOSS_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Python SDK

python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio, os

async def main():
    params = StdioServerParameters(
        command="uvx",
        args=["stoploss-mcp"],
        env={"STOPLOSS_API_KEY": os.environ["STOPLOSS_API_KEY"]},
    )
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as session:
            await session.initialize()

            # Run a natural-language screen
            result = await session.call_tool(
                "screen_stocks",
                {"query": "momentum breakout with high ROE"}
            )
            print(result.content[0].text)

asyncio.run(main())

Authentication#

All requests require a bearer key passed via the STOPLOSS_API_KEY environment variable. Keys are prefixed sk_live_ for production and sk_test_ for sandbox.

⚠ Never commit your API key to source control. Use environment variables or a secrets manager.

Tools Reference#

Every tool returns a structured JSON object. All responses include a data_as_of timestamp. On failure, the response contains {"error": "...", "status": "failed"}.

screen_stocks

Natural-language stock screener. Parses your query into structured filters and runs them against all NSE/BSE equities.

Parameter	Type		Description
query	string	required	Natural-language screen query. E.g. 'profitable small caps with low debt and momentum'

json

// Example response
{
  "query": "profitable small caps with low debt and momentum",
  "interpreted_query": "market_cap < 5000 AND net_profit > 0 AND debt_equity < 0.5 AND rsi_14 > 55",
  "confidence": 0.91,
  "results": [
    {
      "symbol": "KPITTECH",
      "company_name": "KPIT Technologies Ltd",
      "sector": "IT",
      "pe_ratio": 42.1,
      "roe": 22.3,
      "rsi_14": 68.4,
      "technical_score": 87,
      "trend_direction": "UPTREND"
    }
  ],
  "count": 14,
  "ai_basket_summary": "Growth-oriented small-cap IT and manufacturing names with clean balance sheets...",
  "data_as_of": "2026-09-30T08:00:00Z"
}

run_predefined_screen

Runs one of 35 institutional-grade pre-built screens by name.

Parameter	Type		Description
screen_name	string	required	Name of the predefined screen (see list below)

Available screens (35 total)

vcp_breakoutmomentum_leadersvalue_compoundershigh_quality_growthnet_net_grahampiotroski_strongbeneish_cleanlow_debt_high_roe52w_high_breakoutrs_top_percentilesmart_money_accumulationwyckoff_springdividend_aristocratsearnings_accelerationsector_rotation_leadersturnaround_candidateshidden_gems_smallcapfii_buying_surge... and 17 more

batch_screen_stocks

Compare up to 20 tickers side-by-side. Returns a comparison table with rankings.

Parameter	Type		Description
tickers	string[]	required	Array of NSE symbols. Max 20.
fields	string[]	optional	Fields to return. Defaults to PE, ROE, RSI, technical_score, trend.

get_fundamental_analysis

Full forensic analysis of a single stock: Beneish M-Score, Altman Z-Score, Piotroski F-Score, DuPont decomposition, and a quality composite score.

Parameter	Type		Description
ticker	string	required	NSE symbol. E.g. 'HDFCBANK', 'RELIANCE', 'INFY'

json

{
  "symbol": "HDFCBANK",
  "company_name": "HDFC Bank Ltd",
  "beneish_m_score": -2.84,
  "beneish_interpretation": "LOW_MANIPULATION_RISK",
  "altman_z_score": 4.21,
  "altman_zone": "SAFE",
  "piotroski_f_score": 8,
  "piotroski_strength": "STRONG",
  "dupont": {
    "net_profit_margin": 0.183,
    "asset_turnover": 0.09,
    "equity_multiplier": 9.8,
    "roe": 0.161
  },
  "quality_score": "A+",
  "moat_rating": "WIDE",
  "recommendation": "BUY",
  "confidence": "92%",
  "data_as_of": "2026-09-30T08:00:00Z"
}

get_technical_analysis

Technical signal suite. Use lite mode for fast pre-computed signals (~50ms), or full mode for deep analysis including VCP detection, Smart Money divergence, and multi-timeframe EMA alignment.

Parameter	Type		Description
ticker	string	required	NSE symbol
mode	"lite" \| "full"	optional	Default: "full". Use "lite" for speed in screener workflows.
start_date	string	optional	ISO date. E.g. '2025-01-01'. Defaults to 1 year.
end_date	string	optional	ISO date. Defaults to today.

get_advanced_analysis

Institutional-grade quant modules: Smart Money Flow, DCF valuation, Wyckoff phase detection, and optimal position sizing.

Parameter	Type		Description
ticker	string	required	NSE symbol
analysis_types	string[]	optional	Subset of: ["smart_money","dcf","wyckoff","position_sizing"]. Defaults to all.

get_news_sentiment

Fetches recent news and scores sentiment using NLP. Returns per-article impact scores and aggregated themes. Always live — not cached.

Parameter	Type		Description
ticker	string	required	NSE symbol
company_name	string	optional	Optional override for news search query

get_recommendation

AI-generated BUY / HOLD / SELL verdict synthesising fundamental, technical, and sentiment signals. Pass pre-fetched data to skip re-fetching and reduce latency.

Parameter	Type		Description
ticker	string	required	NSE symbol
fundamental_data	object	optional	Pass output of get_fundamental_analysis to avoid re-fetching
technical_data	object	optional	Pass output of get_technical_analysis to avoid re-fetching

get_peer_comparison

Benchmarks a stock against its sector peers and returns relative percentile ranks.

Parameter	Type		Description
ticker	string	required	NSE symbol

get_stock_ratios

Returns the full ratio snapshot for a ticker: valuation, profitability, leverage, efficiency, and growth.

Parameter	Type		Description
ticker	string	required	NSE symbol

list_available_stocks

Returns all NSE/BSE symbols in the database with sector and industry metadata. Use to validate tickers before calling analysis tools.

json

// No parameters required
{
  "count": 2847,
  "coverage": "NSE + BSE",
  "stocks": [
    { "symbol": "HDFCBANK", "company_name": "HDFC Bank Ltd", "sector": "Financials", "industry": "Private Banks" },
    { "symbol": "RELIANCE", "company_name": "Reliance Industries Ltd", "sector": "Energy", "industry": "Oil & Gas" }
  ],
  "data_as_of": "2026-09-30T08:00:00Z"
}

Rate Limits#

Tier	Tool Calls / min	Tool Calls / month	Notes
Free	10	5,000	API key required
Developer	60	200,000	Pay-as-you-go after limit
Enterprise	300	Unlimited	Dedicated infra, SLA-backed

Error Reference#

Error Code	HTTP Status	Meaning
UNAUTHORIZED	401	Missing or invalid STOPLOSS_API_KEY
TICKER_NOT_FOUND	404	Symbol not in the database. Call list_available_stocks to validate.
RATE_LIMIT	429	Too many requests. Back off and retry with exponential jitter.
ANALYSIS_FAILED	500	Upstream computation error. The response will include a descriptive error string.
TOOL_UNAVAILABLE	503	Temporary maintenance. Check status.stoploss.ai.

Changelog#

v2.0.0latestSep 2026

New: TimesFM 2.0 momentum scoring integrated into get_technical_analysis
New: Wyckoff phase detection in get_advanced_analysis
New: 35 predefined screens via run_predefined_screen
Improved: screen_stocks confidence scoring (+12% accuracy)
SSE transport now stable for long-running sessions

v1.3.0Jul 2026

Added batch_screen_stocks — compare up to 20 tickers
Added get_peer_comparison with sector percentile ranks
Reduced P95 latency from 350ms → 183ms

v1.0.0May 2026

Initial release: 8 tools, NSE coverage, stdio transport