Toolstem MCP server

📊 Toolstem — Financial Data MCP for AI Agents | Stock Analysis & DCF

Curated financial data MCP for AI agents — equity research in one call.

Toolstem is the financial data MCP built for AI stock analysis, equity research, and agent-driven investment workflows. Real-time stock data, company fundamentals, DCF valuations, financial metrics, and the ability to compare companies side-by-side — all returned as flat, agent-friendly JSON with derived signals already computed.

Works natively with Claude, OpenAI Agents SDK, and LangChain. Pay-per-call pricing, no subscription. More finance MCP servers (SEC filings, insider transactions, institutional holdings) are on the way.

Unlike passthrough wrappers that just expose a vendor's REST API, every Toolstem tool combines multiple data sources, derives signals, and pre-computes the math an agent would otherwise have to do itself.

One call. One agent-friendly JSON response. No nested arrays to parse, no cross-endpoint stitching, no null-checking boilerplate.

---

Quickstart — hosted endpoint (recommended)

Point your MCP client or agent at the hosted endpoint. No API key, no infra, no setup. Billing is per-call via x402 — the agent's wallet pays directly in USDC on Base mainnet.

https://mcp.toolstem.com/mcp/finance

• No FMP API key required — you do not bring or manage any upstream data key.
• No infrastructure — nothing to install, host, or keep running.
• No setup — connect an MCP client and call a tool.
• initialize and tools/list are free (discovery and schema introspection).
• Each tools/call costs $0.01 USDC on Base mainnet, settled via x402.

Claude Desktop

Drop this into your claude_desktop_config.json:

{
  "mcpServers": {
    "toolstem-finance": {
      "url": "https://mcp.toolstem.com/mcp/finance"
    }
  }
}

Restart Claude Desktop, then ask: "Use Toolstem to get a snapshot of NVDA."

Any MCP client (LangChain.js)

The official @langchain/mcp-adapters library connects directly to the hosted URL:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const client = new MultiServerMCPClient({
  toolstem_finance: {
    transport: "http",
    url: "https://mcp.toolstem.com/mcp/finance",
    // Add your x402-signing middleware via headers, OR run an x402
    // proxy locally and point url at it. See https://www.x402.org/clients.
  },
});

const tools = await client.getTools();
const agent = createReactAgent({ llm: new ChatOpenAI({ model: "gpt-4o-mini" }), tools });
await agent.invoke({ messages: "Compare AAPL, MSFT, and GOOGL on valuation and growth." });

LangChain quick-start (langchain-toolstem)

The langchain-toolstem wrapper handles x402 payment for you — pass a funded wallet key and the tools auto-pay per call:

import { createToolstemTools } from 'langchain-toolstem';
const tools = await createToolstemTools({ walletPrivateKey: process.env.WALLET_KEY });
// Tools auto-pay $0.01 USDC per call via x402

Prefer to run the server yourself with your own FMP key? See Advanced: self-host at the bottom.

Try the tools live in the Toolstem playground.

Product page: https://toolstem.com/finance/.

---

Pricing

• MCP initialize and tools/list are free — discovery, schema introspection, and health checks never cost anything.
• tools/call costs $0.01 USDC on Base mainnet per invocation, paid via x402. No API key, no signup, no marketplace account required — the agent's wallet pays directly.

Tool	Per call
get_stock_snapshot	$0.01 USDC
get_company_metrics	$0.01 USDC
compare_companies	$0.01 USDC

How billing works

Toolstem uses the x402 payment protocol. Agents pay per call in USDC on Base — no API keys, no subscriptions, no invoices. The agent's wallet settles each call automatically via EIP-3009.

---

How it works

Toolstem ships as a Node MCP server (this repo) and as a hosted, x402-gated proxy.

Agent ──MCP──▶ Cloudflare Worker (x402 paywall) ──MCP──▶ Toolstem MCP server ──REST──▶ Financial Modeling Prep
                  │                                          │
                  └─ free: initialize, tools/list            └─ composite tool: fans out to 3–5 FMP endpoints
                  └─ paid: tools/call → 0.01 USDC on Base       in parallel, derives signals, returns flat JSON

• Cloudflare Worker terminates the public MCP connection at mcp.toolstem.com and enforces the x402 payment for tools/call.
• MCP server (this package) implements the 3 composite tools and talks to Financial Modeling Prep.
• x402 on Base mainnet handles the micropayment — settlement is sub-second, no off-chain accounts.

---

Tools

Three composite tools, each one synthesizing multiple FMP endpoints with derived signals and pre-computed math.

Tool	Title	Required input	Optional input
get_stock_snapshot	Stock Snapshot	symbol (string)	—
get_company_metrics	Company Metrics	symbol (string)	period (annual | quarter, default annual)
compare_companies	Company Comparison	symbols (string[2..5])	—

All three are read-only, idempotent, and safe for agent retry.

get_stock_snapshot

Comprehensive stock overview combining quote, profile, DCF valuation, and rating into a single response.

Input:

{
  "symbol": "AAPL"
}

Example output (truncated):

{
  "symbol": "AAPL",
  "company_name": "Apple Inc.",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "exchange": "NASDAQ",
  "price": {
    "current": 178.52,
    "change": 2.34,
    "change_percent": 1.33,
    "day_high": 179.80,
    "day_low": 175.10,
    "year_high": 199.62,
    "year_low": 130.20,
    "distance_from_52w_high_percent": -10.57,
    "distance_from_52w_low_percent": 37.11
  },
  "valuation": {
    "market_cap": 2780000000000,
    "market_cap_readable": "$2.78T",
    "pe_ratio": 29.5,
    "dcf_value": 195.20,
    "dcf_upside_percent": 9.35,
    "dcf_signal": "FAIRLY VALUED"
  },
  "rating": {
    "score": 4,
    "recommendation": "Buy",
    "dcf_score": 5,
    "roe_score": 4,
    "roa_score": 4,
    "de_score": 5,
    "pe_score": 3
  },
  "fundamentals_summary": {
    "beta": 1.28,
    "avg_volume": 55000000,
    "employees": 164000,
    "ipo_date": "1980-12-12",
    "description": "Apple Inc. designs, manufactures..."
  },
  "meta": {
    "source": "Toolstem via Financial Modeling Prep",
    "timestamp": "2026-04-17T18:30:00Z",
    "data_delay": "End of day"
  }
}

Derived fields (not in raw APIs):

• dcf_signal — UNDERVALUED if DCF upside > 10%, OVERVALUED if < -10%, else FAIRLY VALUED.
• market_cap_readable — human-friendly $2.78T, $450.2B, $12.5M format.
• distance_from_52w_high_percent / distance_from_52w_low_percent — pre-computed range position.

---

get_company_metrics

Deep fundamentals analysis — profitability, financial health, cash flow, growth, and per-share metrics — synthesized from 5 financial statements endpoints.

Input:

{
  "symbol": "AAPL",
  "period": "annual"
}

period accepts annual (default) or quarter.

Example output (truncated):

{
  "symbol": "AAPL",
  "period": "annual",
  "latest_period_date": "2025-09-30",
  "profitability": {
    "revenue": 394328000000,
    "revenue_readable": "$394.3B",
    "revenue_growth_yoy": 7.8,
    "net_income": 96995000000,
    "net_income_readable": "$97.0B",
    "gross_margin": 46.2,
    "operating_margin": 31.5,
    "net_margin": 24.6,
    "roe": 160.5,
    "roa": 28.3,
    "roic": 56.2,
    "margin_trend": "EXPANDING"
  },
  "financial_health": {
    "total_debt": 111000000000,
    "total_cash": 65000000000,
    "net_debt": 46000000000,
    "debt_to_equity": 1.87,
    "current_ratio": 1.07,
    "interest_coverage": 41.2,
    "health_signal": "STRONG"
  },
  "cash_flow": {
    "operating_cash_flow": 118000000000,
    "free_cash_flow": 104000000000,
    "free_cash_flow_readable": "$104.0B",
    "fcf_margin": 26.4,
    "capex": 14000000000,
    "dividends_paid": 15000000000,
    "buybacks": 89000000000,
    "fcf_yield": 3.7
  },
  "growth_3yr": {
    "revenue_cagr": 8.2,
    "net_income_cagr": 10.1,
    "fcf_cagr": 9.5,
    "growth_signal": "ACCELERATING"
  },
  "per_share": {
    "eps": 6.42,
    "book_value_per_share": 3.99,
    "fcf_per_share": 6.89,
    "dividend_per_share": 0.96,
    "payout_ratio": 14.9
  },
  "meta": {
    "source": "Toolstem via Financial Modeling Prep",
    "timestamp": "2026-04-17T18:30:00Z",
    "periods_analyzed": 3,
    "data_delay": "End of day"
  }
}

Derived fields:

• margin_trend — EXPANDING, STABLE, or CONTRACTING based on net margin series direction.
• health_signal — STRONG, ADEQUATE, or WEAK from debt-to-equity, current ratio, and interest coverage.
• growth_signal — ACCELERATING, STEADY, or DECELERATING based on YoY growth trajectory.
• revenue_cagr, net_income_cagr, fcf_cagr — compound annual growth rates over the analyzed window.
• fcf_margin, fcf_yield — pre-computed from cash flow + revenue + market cap.

---

compare_companies

Side-by-side comparison of 2–5 companies across price, valuation, profitability, financial health, growth, dividends, and analyst ratings.

Input:

{
  "symbols": ["AAPL", "MSFT", "GOOGL"]
}

symbols must be an array of 2 to 5 ticker strings.

Example output (truncated):

{
  "symbols_compared": ["AAPL", "MSFT", "GOOGL"],
  "comparison_date": "2026-04-20T18:30:00Z",
  "companies": [
    {
      "symbol": "AAPL",
      "company_name": "Apple Inc.",
      "sector": "Technology",
      "price": { "current": 178.52, "change_percent": 1.33 },
      "valuation": { "pe_ratio": 29.5, "dcf_upside_percent": 9.35 },
      "profitability": { "net_margin": 24.6, "roe": 160.5, "roic": 56.2 },
      "financial_health": { "debt_to_equity": 1.87, "current_ratio": 1.07 },
      "growth": { "revenue_growth_yoy": 7.8, "earnings_growth_yoy": 10.1 },
      "dividend": { "dividend_yield": 0.5, "payout_ratio": 14.9 },
      "rating": { "score": 4, "recommendation": "Buy" }
    }
  ],
  "rankings": {
    "lowest_pe": "GOOGL",
    "highest_margin": "AAPL",
    "strongest_balance_sheet": "GOOGL",
    "best_growth": "MSFT",
    "most_undervalued": "GOOGL",
    "highest_rated": "MSFT"
  },
  "meta": {
    "source": "Toolstem via Financial Modeling Prep",
    "timestamp": "2026-04-20T18:30:00Z",
    "data_delay": "Real-time during market hours",
    "api_calls_made": 19
  }
}

Derived fields:

• rankings — automatically computed: lowest_pe, highest_margin, strongest_balance_sheet, best_growth, most_undervalued, highest_rated.
• All valuation, profitability, health, and growth metrics pre-computed per company.
• Uses batch quote for efficient multi-symbol price retrieval.

---

Why Toolstem?

Most financial MCP servers expose one tool per API endpoint — forcing your agent to make 4–5 sequential calls, write glue code, and reason about raw data shapes. Toolstem is built differently:

• Parallel data fetching — every tool fans out to multiple sources concurrently.
• Derived signals — human-readable recommendations like UNDERVALUED, STRONG, ACCELERATING computed from raw numbers.
• Pre-computed math — CAGRs, YoY growth, margin trends, distance from 52-week high/low, FCF yield, and more are already in the response.
• Flat, predictable schema — no deeply nested vendor quirks leaking into agent prompts.
• Graceful degradation — if one upstream endpoint fails, the rest of the response still comes through with nulls in place.

---

Advanced: self-host

Most users should use the hosted endpoint above — it needs no API key, no infrastructure, and no setup. This section is for users who specifically want to run the server themselves.

Run the Node MCP server locally with your own FMP key — no x402, no per-call charge beyond your FMP quota. You are responsible for obtaining and managing your own FMP_API_KEY and for any infrastructure you run.

npm

npm install -g toolstem-mcp-server

stdio (default — for Claude Desktop, Cursor, etc.):

FMP_API_KEY=your_key_here toolstem-mcp-server

HTTP — local only (default, binds 127.0.0.1):

FMP_API_KEY=your_key_here toolstem-mcp-server --http

HTTP — remote + auth (binds 0.0.0.0, requires bearer token):

FMP_API_KEY=your_key ALLOW_REMOTE=1 MCP_AUTH_TOKEN=my-secret toolstem-mcp-server --http

Clients must send Authorization: Bearer my-secret on every /mcp request.

HTTP — auth disabled (local only):

FMP_API_KEY=your_key MCP_AUTH_DISABLED=1 toolstem-mcp-server --http

MCP_AUTH_DISABLED=1 forces the server to bind 127.0.0.1 regardless of ALLOW_REMOTE. This is a safe "skip auth, local only" mode for development.

HTTP — remote without auth (dangerous):

FMP_API_KEY=your_key ALLOW_REMOTE=1 MCP_AUTH_DISABLED=1 I_KNOW_THIS_IS_DANGEROUS=1 toolstem-mcp-server --http

Warning: This exposes your FMP API key to anyone who can reach the port. Requires all three env vars. A [SECURITY WARNING] banner prints at startup and repeats every 60 seconds. Only use for trusted networks or development.

Claude Desktop (self-hosted)

{
  "mcpServers": {
    "toolstem": {
      "command": "npx",
      "args": ["-y", "toolstem-mcp-server"],
      "env": {
        "FMP_API_KEY": "your_fmp_api_key"
      }
    }
  }
}

From source

npm install
npm run build
FMP_API_KEY=your_key npm run start:http

---

Environment Variables

Variable	Required	Description
FMP_API_KEY	Yes (self-hosted)	Financial Modeling Prep API key. Get one at financialmodelingprep.com. Not needed when calling the hosted endpoint.
PORT	No	Port for HTTP transport. Defaults to 3000.
ALLOW_REMOTE	No	Set to 1 to bind HTTP on 0.0.0.0 instead of 127.0.0.1.
MCP_AUTH_TOKEN	When ALLOW_REMOTE=1	Bearer token for authenticating /mcp requests.
MCP_AUTH_DISABLED	No	Set to 1 to skip auth. Forces 127.0.0.1 bind unless I_KNOW_THIS_IS_DANGEROUS=1 is also set.
I_KNOW_THIS_IS_DANGEROUS	No	Set to 1 alongside ALLOW_REMOTE=1 and MCP_AUTH_DISABLED=1 to allow remote access without auth. Triggers a periodic warning banner.

---

Development

npm install
npm run dev           # stdio, hot reload via tsx
npm run build         # TypeScript -> dist/
npm start             # run built stdio server
npm run start:http    # run built HTTP server

---

Architecture

src/
├── index.ts          # MCP server entry (stdio + Streamable HTTP)
├── actor.ts          # Apify Actor entry (legacy)
├── services/
│   └── fmp.ts        # Financial Modeling Prep API client
├── tools/
│   ├── get-stock-snapshot.ts
│   ├── get-company-metrics.ts
│   └── compare-companies.ts
└── utils/
    └── formatting.ts # Market cap formatting, CAGR, trend signals

All FMP endpoints are wrapped in a single FmpClient class. Tool implementations fan out to multiple client methods in parallel via Promise.all, then synthesize the merged result.

---

License

MIT — see LICENSE.

---

Toolstem — curated financial intelligence for the agent-native economy. https://toolstem.com/finance/