MCP server (AI agents)

The Sentiment402 MCP adapter exposes snapshot endpoints as MCP tools for agent runtimes (Claude Desktop, ChatGPT Desktop, Cline, Cursor, etc.). It calls the public Sentiment402 HTTPS API and handles x402 payment requirements.

Repository: https://github.com/kytona/mcp

Tool mapping

These tools map 1:1 to API endpoints:

MCP Tool	API endpoint	Description
get_global_snapshot	GET /v1/snapshot/global	Global market sentiment snapshot
get_crypto_pulse	GET /v1/snapshot/crypto	Crypto market sentiment pulse
get_tradfi_pulse	GET /v1/snapshot/tradfi	TradFi market sentiment pulse
get_asset_view	GET /v1/snapshot/asset/:symbol	Asset-specific sentiment view

Note: The MCP adapter currently only supports v1 endpoints. Payments are made on Base (EVM) network only.

Tool inputs

All tools accept these optional inputs:

• format (optional): "full" or "compact_trading" (defaults to "full")

• fields (optional): Comma-separated allowlist (only meaningful when format="compact_trading")

The get_asset_view tool additionally requires:

• symbol (required): Asset ticker (e.g., "BTC", "ETH", "NVDA")

Example tool call:

{
  "format": "compact_trading",
  "fields": "ts,mood,rec"
}

Payment handling

The adapter supports two payment modes:

1. Human-in-the-loop: Returns a structured PAYMENT_REQUIRED payload when the API responds with 402. The agent/operator can then handle payment manually.

2. Auto-pay: If SENTIMENT402_X402_PRIVATE_KEY is configured, the adapter automatically signs and retries 402 responses. Payment attempts are logged to stdout.

When auto-pay fails or is not configured, the adapter returns a PAYMENT_REQUIRED payload with payment options:

{
  "error": "PAYMENT_REQUIRED",
  "x402Version": 1,
  "resource": "https://sentiment-api.kytona.com/v1/snapshot/global",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "USDC",
      "amount": "20000",
      "payTo": "0x..."
    }
  ]
}

Note: Payments are only supported on Base (EVM) network. Solana payments are not available in the MCP adapter.

Caching

The adapter uses an in-memory cache to reduce redundant paid calls:

• Default TTL: 60 seconds (configurable via SENTIMENT402_CACHE_TTL_MS)

• Cache key: {tool}:{path}?{query}

• Only 2xx JSON responses are cached

• 402 responses are never cached

Configuration

Environment variables:

• SENTIMENT402_API_BASE_URL (optional): API base URL (default: https://sentiment-api.kytona.com)

• SENTIMENT402_CACHE_TTL_MS (optional): Cache TTL in milliseconds (default: 60000)

• SENTIMENT402_USER_AGENT (optional): User agent string (default: sentiment402-mcp/0.1.0)

• SENTIMENT402_X402_PRIVATE_KEY (optional): Base (EVM) private key for auto-paying x402 requests

• SENTIMENT402_X402_MAX_PAYMENT (optional): Maximum payment in base units (default: 100000, i.e., $0.10 USDC)

Note: The adapter uses v1 endpoints only. Payments are made on Base network using USDC.

Setup

Quick start (NPX)

Run directly from GitHub without installation:

{
  "mcpServers": {
    "sentiment402": {
      "command": "npx",
      "args": ["-y", "github:kytona/mcp"],
      "env": {
        "SENTIMENT402_X402_PRIVATE_KEY": "your_base_evm_private_key_here"
      }
    }
  }
}

Local installation

1. Clone and build:

git clone https://github.com/kytona/mcp.git
cd mcp
pnpm install
pnpm build

1. Configure your MCP client:

{
  "mcpServers": {
    "sentiment402": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"],
      "env": {
        "SENTIMENT402_X402_PRIVATE_KEY": "your_base_evm_private_key_here"
      }
    }
  }
}

See the MCP adapter README for detailed setup instructions for Claude Desktop, ChatGPT Desktop, and other MCP clients.

Safety notes

• Never paste wallet private keys into prompts or logs

• The adapter is stateless and contains no database credentials

• Auto-pay respects SENTIMENT402_X402_MAX_PAYMENT to prevent accidental large payments

• The adapter only calls the public HTTPS API and never accesses internal systems