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

Related MCP server: BlackSwan MCP Server

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

Signal Tools

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

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