🕵️ 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