Alchm.kitchen MCP Server

An MCP server exposing five alchemical tools — live sky transits, ingredient ESMS analysis, cosmic recipe discovery, synastry overlays, and transit×natal overlays — to any LLM client that speaks MCP (Claude Desktop, Cursor, Google Antigravity, Claude Agent SDK, etc.).

Install

# Bun (recommended)
bunx @alchm/mcp-server

# Node / npx
npx -y @alchm/mcp-server

Or install globally:

bun add -g @alchm/mcp-server
alchm-mcp-server

Tools

generate_cosmic_recipe debits tokens only when called with a valid _meta.apiKey. Anonymous callers receive a QUOTA error rather than a free recipe. The other four tools are free.

Mint an API key

End users mint, list, and revoke their own keys at /profile/api-keys. The plaintext is shown exactly once — paste it into the MCP client config immediately. The public onboarding doc lives at /docs/mcp.

Keys are stored as sha256(plaintext) in the api_keys table; the only place the plaintext ever appears is the POST /api/account/api-keys response body.

Run from source

bun run mcp-server/src/index.ts

Optional env:

ALCHM_MCP_BACKEND_URL=https://alchm.kitchen  # alchm.kitchen host the chart/transit tools fetch /api/astrologize from
DATABASE_URL=postgres://...           # enables token gate + invocation telemetry
MCP_USER_API_KEY=sk_alchm_...         # single-user setups (Claude Desktop)
INTERNAL_API_SECRET=...               # synthetic-probe exempt path (set by Vercel cron)
SYNTHETIC_PROBE_USER_ID=<uuid>        # attribute synthetic-probe invocations to this user

ALCHM_MCP_BACKEND_URL — where chart/transit tools fetch from

get_live_sky_transits and get_transit_natal_overlay build a natal chart by POSTing to <base>/api/astrologize, a route served by the alchm.kitchen Next.js app. This server runs standalone (no co-located backend), so <base> is resolved as:

1. ALCHM_MCP_BACKEND_URL (or SITE_URL / Vercel envs) — explicit, always wins.
2. Bundled artifacts — the npm dist/index.js and the bun build --compile binary (bin/alchm-mcp) default to https://alchm.kitchen, since an end-user machine has no local backend.
3. From-source dev (bun run mcp-server/src/index.ts) defaults to http://localhost:3000 — run bun run dev alongside, or set ALCHM_MCP_BACKEND_URL, to point it elsewhere.

When the backend is unreachable the tools fail loud with the attempted URL and this env var name, rather than a bare "fetch failed". Build the desktop sidecar binary with bun run --cwd mcp-server build:binary → mcp-server/bin/alchm-mcp.

When DATABASE_URL is absent the server still runs — all calls become anonymous, the token gate skips, and invocations are not logged.

Per-call auth

Every tool accepts an optional _meta field on its arguments:

{
  "name": "generate_cosmic_recipe",
  "arguments": {
    "prompt": "spicy",
    "cuisine": "thai",
    "_meta": {
      "apiKey": "sk_alchm_live_xxx",
      "caller": "claude-desktop"
    }
  }
}

• _meta.apiKey resolves to an api_keys row → bound user → ESMS debit happens against that user's balance.
• _meta.caller is a free-form identifier (e.g. "claude-desktop", "cursor", "pa-mcp") persisted on the invocation row.

If MCP_USER_API_KEY is set in the environment, it is used as the default apiKey for every call — convenient for single-user installs.

Connecting Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "alchm-kitchen": {
      "command": "bun",
      "args": [
        "run",
        "/absolute/path/to/WhatToEatNext-master/mcp-server/src/index.ts"
      ],
      "env": {
        "DATABASE_URL": "postgres://...",
        "MCP_USER_API_KEY": "sk_alchm_live_xxx"
      }
    }
  }
}

See claude-desktop.config.example.json in this directory for a copy-paste template.

Connecting Cursor

Add to ~/.cursor/mcp.json or the project's .cursor/mcp.json:

{
  "mcpServers": {
    "alchm-kitchen": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/WhatToEatNext-master/mcp-server/src/index.ts"],
      "env": {
        "MCP_USER_API_KEY": "sk_alchm_live_xxx"
      }
    }
  }
}

Telemetry & Operations

Every successful or failed tool call writes a row to mcp_invocations (Postgres). Surfaces:

• Admin dashboard — /admin System Status panel now includes an MCP Tool Surface flow showing call rate, error rate, p95 latency, and the synthetic probe verdict.
• Agent Telemetry — mcpInvocationRate joins transmutationRate, spiritualEntropy, and agentHarmony as a live metric on the High Alchemist dashboard.
• Synthetic probe — /api/cron/synthetic-mcp exercises the tool layer every 30 minutes; failures downgrade the dashboard verdict to INCIDENT even with zero organic MCP traffic.

Testing

• bun test src/lib/mcp/__tests__/tools.test.ts — unit tests for the tool handlers + auth gate.
• MCP_E2E=1 bun test mcp-server/src/__tests__/stdio.test.ts — spawns the actual server and verifies the JSON-RPC handshake + tools/list + a tools/call round-trip.

Architecture

See ARCHITECTURE.md for the two-server topology (Alchm MCP + PA MCP) and the cross-server bridge that lets PA personas ground their responses in live alchm.kitchen state.