Tokonomix in Claude Code

This guide walks you through adding the Tokonomix consensus MCP server to a Claude Code project so your coding agent can call a multi-model council for review gates, security checks, and fact-checking.

Prerequisites

A Tokonomix API key (tok_live_...) — obtain one from https://tokonomix.ai
Node.js 18+ (for npx)
Claude Code 1.x

Step 1 — Add the MCP server to your project

In the project root, run:

claude mcp add tokonomix-council-mcp -- npx tokonomix-mcp

Or add it manually to .claude/settings.json:

{
  "mcpServers": {
    "tokonomix": {
      "command": "npx",
      "args": ["tokonomix-mcp"],
      "env": {
        "TOKONOMIX_API_KEY": "tok_live_..."
      }
    }
  }
}

Security: store the key in an env var from your shell, not in the JSON file itself. In .claude/settings.json you can reference shell env vars: "TOKONOMIX_API_KEY": "${TOKONOMIX_API_KEY}".

Step 2 — Verify the connection

Inside a Claude Code session:

/mcp

You should see tokonomix listed with status connected. If not, check that npx resolves correctly (which npx) and that TOKONOMIX_API_KEY is set in your shell.

Step 3 — Use the consensus tools

The MCP server exposes these tools (usable directly in Claude Code prompts):

Tool	What it does
`tokonomix_consensus_ask`	Send a question to a multi-model council and get a synthesised answer
`tokonomix_single_ask`	Send a question to a single model (no council)
`tokonomix_rate_consensus`	Rate a previous consensus answer (thumbs up/down + optional note)
`tokonomix_get_balance`	Check your remaining credit balance
`tokonomix_list_models`	List available models with their capabilities
`tokonomix_get_skill`	Fetch a named skill document

Example prompt

Use tokonomix_consensus_ask to review this function for security issues:

<paste function here>

Claude Code will call the tool, send the code to a multi-model council, and return the synthesised review with any disagreements surfaced.

Step 4 — Use as a review gate in an unattended run

The Agents Never Sleep harness uses tokonomix_consensus_ask as its built-in review gate. When you run ANS with a council credential configured, each ticket automatically goes through a 5-model/3-judge gate before commit.

To set up the credential for ANS:

mkdir -p ~/.tokonomix
echo '{"apiKey":"tok_live_..."}' > ~/.tokonomix/credentials.json
chmod 600 ~/.tokonomix/credentials.json

ANS reads this file; it does NOT use ANTHROPIC_API_KEY for council calls.

Step 5 — Use the gateway directly (chat, images, embeddings)

The gateway is also available as a plain HTTP endpoint from within scripts or tools. Use the OpenAI SDK pointed at the Tokonomix base URL:

import OpenAI from "openai";

const toko = new OpenAI({
  baseURL: "https://tokonomix.ai/api/v1",
  apiKey: process.env.TOKONOMIX_API_KEY ?? "",
});

// Single-model chat
const resp = await toko.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Summarise this diff: ..." }],
});

// Embeddings
const emb = await toko.embeddings.create({
  model: "text-embedding-3-small",
  input: "some text to embed",
});

Troubleshooting

Symptom	Likely cause	Fix
`tokonomix` not listed in `/mcp`	`npx` not on PATH	Run `which npx`; install Node.js
`401 Unauthorized`	Wrong or missing key	Check `TOKONOMIX_API_KEY` in shell
`402 Payment Required`	Credit balance exhausted	Top up at https://tokonomix.ai
`429` during council call	Rate limit	Reduce concurrency or space out calls
Council returns no answer	All proposers refused	Rephrase the prompt; check for disallowed content

MCP server version

Latest published version: 1.6.2 (npm: tokonomix-council-mcp).

npx tokonomix-mcp --version

Registry metadata: GET https://tokonomix.ai/.well-known/mcp/server.json