Sentiment402 MCP Adapter (stdio)

A thin MCP server that exposes Sentiment402 snapshot endpoints as MCP tools. It calls the public Sentiment402 API over HTTPS and relays x402 payment requirements when the API responds with 402 Payment Required.

This adapter is intentionally stateless and contains no database credentials or admin headers. It is safe to run locally or package as a public MCP tool.

Tool surface

Common inputs

All tools accept the same optional query inputs (and get_asset_view additionally requires a symbol).

• format: full or compact_trading

• fields: comma-separated allowlist (only meaningful when format=compact_trading)

• symbol: required for get_asset_view

Example tool arguments:

{
  "format": "compact_trading",
  "fields": "headline,trend,confidence"
}

x402 payment handling

When the Sentiment402 API responds with 402, the adapter returns a structured PAYMENT_REQUIRED payload. If SENTIMENT402_X402_PRIVATE_KEY is configured, it will attempt an x402 payment automatically using the options returned by the API. If the payment cannot be completed, the PAYMENT_REQUIRED payload is returned.

Example payload (truncated):

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

Caching

A small in-memory cache is used to reduce repeated requests.

• Default TTL: 60000 ms

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

• Only 2xx JSON responses are cached

• 402 responses are never cached

Configuration

Defaults:

• API base URL: https://sentiment-api.kytona.com

• API version: v1

Environment variables:

• SENTIMENT402_API_BASE_URL (optional) — default https://sentiment-api.kytona.com

• SENTIMENT402_API_VERSION (optional) — v1 (default v1)

• SENTIMENT402_CACHE_TTL_MS (optional) — cache TTL in ms (default 60000)

• SENTIMENT402_USER_AGENT (optional) — default sentiment402-mcp/0.1.0

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

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

No API keys are required for the Sentiment402 API. The private key is only needed if you want auto-pay for 402 responses.

Run locally

Build and start:

pnpm install
pnpm build
pnpm start

You can also run directly in dev mode:

pnpm dev

To point at localhost:

SENTIMENT402_API_BASE_URL="http://localhost:8080" pnpm dev

MCP host config example

Example for a stdio MCP host configuration:

{
  "command": "node",
  "args": ["/path/to/sentiment402/mcp/dist/index.js"],
  "env": {
    "SENTIMENT402_API_BASE_URL": "https://sentiment-api.kytona.com",
    "SENTIMENT402_API_VERSION": "v1"
  }
}

Client Setup Instructions

Claude Desktop

Claude Desktop supports MCP servers via stdio configuration.

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Run from GitHub (Recommended)

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

This automatically downloads and runs the latest version from GitHub.

Option 2: Run from Local Clone

1. Clone and build:

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

2. Configure Claude:

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

3. Restart Claude Desktop and look for the 🔌 icon to see available tools.

Resources:

• Claude MCP Documentation

• Using Remote MCP Servers

ChatGPT Desktop

ChatGPT supports MCP via Developer Mode (requires ChatGPT Plus).

Setup Steps

1. Enable Developer Mode:

   • Open ChatGPT → Settings

   • Go to Apps & Connectors → Advanced settings

   • Enable Developer mode

2. Add MCP Server (NPX - Recommended):

   • In Apps & Connectors, click Create

   • Enter:

     • Name: Sentiment402

     • Command: npx

     • Args: -y github:kytona/mcp

     • Environment Variables:

       SENTIMENT402_API_VERSION=v1
       SENTIMENT402_X402_PRIVATE_KEY=your_evm_private_key_here

   • Check I trust this application

   • Click Create

3. Use in Chat:

   • Click the + in the prompt field

   • Go to More → Developer mode

   • Enable the Sentiment402 connector

Using Local Clone

1. Clone and build as described above for Claude

2. In ChatGPT Developer mode, configure:

   • Command: node

   • Args: /absolute/path/to/mcp/dist/index.js

   • Environment Variables: Same as above

Resources:

• ChatGPT MCP Integration

• MCP Developer Documentation

Running on a Cloud Server

To run the MCP server remotely and connect from Claude/ChatGPT:

1. Deploy to Cloud

# On your cloud server (AWS, DigitalOcean, etc.)
git clone https://github.com/kytona/mcp.git
cd mcp
pnpm install
pnpm build

# Run with PM2 for persistence
npm install -g pm2
pm2 start dist/index.js --name sentiment402-mcp
pm2 save
pm2 startup

2. Expose via ngrok (Development Only)

# Install ngrok: https://ngrok.com/download
ngrok tcp 8000

# Note the forwarding address: tcp://0.tcp.ngrok.io:12345

3. Configure Client

For Claude or ChatGPT, update the command to connect via TCP:

{
  "command": "node",
  "args": ["-e", "const net = require('net'); const client = net.connect({host: '0.tcp.ngrok.io', port: 12345}); process.stdin.pipe(client); client.pipe(process.stdout);"]
}

⚠️ Security Warning: ngrok exposes your server publicly. For production, use:

• VPN (Tailscale, WireGuard)

• SSH tunneling

• Proper authentication middleware

Resources:

• Using ngrok with MCP

• MCP Security Best Practices

Other MCP Clients (Cline, etc.)

For other MCP-compatible clients, use a similar stdio configuration:

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

Refer to your client's documentation for the exact config file location.

Test script

The repo includes a stdio test runner that calls a tool and prints the response.

pnpm build
pnpm test:mcp

To point at localhost:

SENTIMENT402_API_BASE_URL="http://localhost:8080" pnpm test:mcp

Optional overrides:

• SENTIMENT402_MCP_TOOL (default get_global_snapshot)

• SENTIMENT402_MCP_TOOL_ARGS (JSON string)

• SENTIMENT402_MCP_SERVER_CMD / SENTIMENT402_MCP_SERVER_ARGS to customize the server process

License

MIT. See LICENSE.

Safety notes

• The adapter only calls the public HTTPS API and never touches internal databases.

• The MCP response body contains only the API response or a PAYMENT_REQUIRED payload.