![MIKO](https://ik.imagekit.io/ueitnjew7/miko_banner.png)

# @projectmiko/mcp-server

[![npm version](https://img.shields.io/npm/v/%40projectmiko%2Fmcp-server)](https://www.npmjs.com/package/@projectmiko/mcp-server)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)

MIKO exposed as a [Model Context Protocol](https://modelcontextprotocol.io)
server. Any MCP-aware client (Claude Desktop, Claude Code, Cursor, OpenAI
Agents, Gemini, or a custom runtime) can call MIKO's capabilities as tools.
Each tool forwards to the [MIKO REST API](https://docs.mikoprotocol.com/docs/technical-architecture/built-with-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.

## Quick start

```sh
npx -y @projectmiko/mcp-server
```

Or point your client at the hosted endpoint — no install at all:

```
https://mcp.mikoprotocol.com/mcp
```

Both need a wallet-signed JWT (see [Auth](#auth)).

## 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).

`miko.narrative` takes the token by address:

```json
{ "token_address": "<token address>" }
```

The former `mint_address` argument remains accepted as a deprecated alias. Do
not provide both names with different values.

## Auth

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

1. `POST /auth/nonce` with `{ "wallet": "<wallet address>" }` → `{ nonce }`.
2. Sign the nonce with the EVM wallet holding your $MIKO on Robinhood Chain —
   a standard EIP-191 personal signature (MetaMask's `personal_sign`).
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)

```json
{
  "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)

```json
{
  "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

```sh
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.example` (systemd) runs the HTTP transport bound to
localhost; `deploy/nginx-mcp.conf.example` terminates TLS and reverse-proxies
`/mcp`, forwarding the `Authorization` header and disabling buffering for SSE.
Point `MIKO_API_BASE` at your REST API endpoint.

## MIKO Protocol

[Website](https://mikoprotocol.com) ·
[Docs](https://docs.mikoprotocol.com) ·
[Insight Dashboard](https://insight.mikoprotocol.com) ·
[REST API reference](https://docs.mikoprotocol.com/docs/technical-architecture/built-with-miko/rest-api) ·
[Open model — Hugging Face](https://huggingface.co/projectmiko/miko-persona-31b) ·
[Ollama](https://ollama.com/projectmiko/miko) ·
[X](https://x.com/project_miko)