🕵️ TokenSpy MCP Server

Give your AI agent access to pitfall intelligence and trading signals.

TokenSpy maintains a curated database of AI pitfalls (common mistakes, failure modes, and gotchas that cost teams real money) and trading signals (data-driven directional indicators). This MCP server lets AI agents like Claude, Cursor, and others query that data directly.

---

Quick Start

npx tokenspy-mcp

That's it. Your AI agent can now search pitfalls and trading signals.

---

Installation

Option 1: npx (no install)

npx tokenspy-mcp

Option 2: Global install

npm install -g tokenspy-mcp
tokenspy-mcp

---

Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "tokenspy": {
      "command": "npx",
      "args": ["-y", "tokenspy-mcp"],
      "env": {
        "TOKENSPY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):

{
  "mcpServers": {
    "tokenspy": {
      "command": "npx",
      "args": ["-y", "tokenspy-mcp"],
      "env": {
        "TOKENSPY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf / Other MCP Clients

Any MCP-compatible client can use this server. Point it at:

npx tokenspy-mcp

The server communicates over stdio using the standard MCP protocol.

---

Available Tools

Pitfall Tools

Tool	Description
search_pitfalls	Search the AI pitfall database by keyword and tags
get_pitfall	Get full details for a specific pitfall
list_pitfalls	List all available pitfalls

Signal Tools

Tool	Description
search_signals	Search trading signals by keyword, ticker, or category
get_signal	Get full details for a specific signal
list_signals	List all available trading signals

---

Tool Examples

Search for AI pitfalls

Agent: "Search for pitfalls related to RAG"

→ search_pitfalls({ query: "RAG" })

Returns:
[
  {
    "id": "pit_rag_001",
    "title": "RAG Retrieval Poisoning",
    "summary": "Attackers inject malicious content into...",
    "price": 4.99,
    "estimatedCostSaved": 50000,
    "tags": ["security", "rag", "retrieval"]
  }
]

Get trading signal details

Agent: "What's the current BTC signal?"

→ search_signals({ ticker: "BTC" })

Returns:
[
  {
    "id": "sig_btc_momentum",
    "name": "BTC Momentum Oscillator",
    "ticker": "BTC",
    "direction": "bullish",
    "winRate": 0.72,
    "price": 9.99,
    "category": "crypto"
  }
]

---

Free vs Paid Tier

	Free	Paid
Search pitfalls	✅	✅
List pitfalls	✅	✅
Pitfall summaries	✅	✅
Full pitfall content	❌	✅
Search signals	✅	✅
List signals	✅	✅
Signal direction & win rate	✅	✅
Full signal methodology	❌	✅

Free tier works without any API key — great for discovery and basic queries.

Paid tier requires a TOKENSPY_API_KEY environment variable. Get your API key at tokenspy.ai.

---

Environment Variables

Variable	Required	Description
TOKENSPY_API_KEY	No	API key for full content access

---

API Documentation

Full API docs are available at tokenspy.ai/docs.

---

How It Works

This package implements the Model Context Protocol (MCP) — an open standard for connecting AI agents to external tools and data sources. When you configure this server in Claude Desktop, Cursor, or any MCP client:

1. The client starts the tokenspy-mcp process
2. Communication happens over stdin/stdout using JSON-RPC
3. The AI agent can discover and call TokenSpy tools
4. All tools are read-only — no destructive operations, ever

---

Development

git clone https://github.com/kypro-ai/tokenspy-mcp.git
cd tokenspy-mcp
npm install
npm run build
npm start

---

License

MIT — see LICENSE.

---

Built with 🕵️ by TokenSpy