@projectmiko/mcp-server

MIKO exposed as a Model Context Protocol server. Any MCP-aware client (Claude Desktop, Cursor, OpenAI Agents, Gemini, or a custom runtime) can call MIKO's capabilities as tools. Each tool forwards to the MIKO REST API, which enforces auth, tier, and quota.

Two transports, one package:

• stdio (default) — the client runs the server locally via npx.
• Streamable HTTP — a hosted endpoint (https://mcp.mikoprotocol.com/mcp) for clients that connect over the network.

Tools

| Tool | REST endpoint | Min tier | |---|---|---| | miko.factcheck | POST /v1/factcheck | Pro | | miko.persona | POST /v1/persona | Pro | | miko.narrative | POST /v1/narrative | Pro | | miko.watchlist | GET /v1/watchlist | Pro | | miko.insights | POST /v1/insights | Holder | | miko.narratives_trending | GET /v1/narratives/trending | Holder |

Tiers are set by the wallet's $MIKO holdings: Holder (≥ $100), Pro (≥ $1,000), Whale (≥ $2,000). A tool admits its listed tier and above; below it the call returns 403 tier_insufficient. Higher tiers also get larger daily quotas.

Each tool result carries _meta with the call's tier, quota_remaining, cache_status, and cache_age (from the REST response headers).

Auth

Every call needs a wallet-signed JWT. Obtain one either from the dashboard (https://api.mikoprotocol.com/dashboard) or via the REST auth flow:

1. POST /auth/nonce with { "wallet": "<base58 pubkey>" } → { nonce }.
2. Sign the nonce string with the wallet's ED25519 key, base58-encode the signature.
3. POST /auth/verify with { wallet, signature, nonce } → { jwt, tier, expires_at, quota }.

The JWT is valid ~24h. Supply it to the server as described below.

Client config

stdio (local, via npx)

{
  "mcpServers": {
    "miko": {
      "command": "npx",
      "args": ["-y", "@projectmiko/mcp-server"],
      "env": { "MIKO_JWT": "<your_wallet_jwt>" }
    }
  }
}

Claude Desktop config path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows).

Streamable HTTP (hosted)

{
  "mcpServers": {
    "miko": {
      "type": "http",
      "url": "https://mcp.mikoprotocol.com/mcp",
      "headers": { "Authorization": "Bearer <your_wallet_jwt>" }
    }
  }
}

Environment variables

| Var | Default | Purpose | |---|---|---| | MIKO_JWT | — | wallet-signed JWT (stdio; for HTTP it comes from the request header) | | MIKO_API_BASE | https://api.mikoprotocol.com | REST API base URL | | MIKO_API_TIMEOUT_MS | 60000 | upstream request timeout | | MIKO_MCP_HTTP | — | set 1 (or pass --http) to run the Streamable HTTP transport | | MIKO_MCP_HTTP_HOST | 127.0.0.1 | HTTP bind host | | MIKO_MCP_HTTP_PORT | 8091 | HTTP bind port | | MIKO_MCP_ALLOWED_ORIGINS | — | comma-separated Origin allowlist (browser callers) |

Develop / run

cd mcp-server
npm install
npm run check          # syntax check
npm test               # smoke tests (no network)

MIKO_JWT=<jwt> node src/index.js          # stdio
node src/index.js --http                   # Streamable HTTP on 127.0.0.1:8091

Self-hosting the HTTP endpoint

deploy/miko-mcp.service (systemd) runs the HTTP transport bound to localhost; deploy/nginx-mcp.conf.example terminates TLS for mcp.mikoprotocol.com and reverse-proxies /mcp, forwarding the Authorization header and disabling buffering for SSE. The service points MIKO_API_BASE at the local REST API (http://127.0.0.1:8090).