MCP Server — zeqsdk-mcp

Model Context Protocol server. Any MCP-compatible LLM client (Claude Desktop, Claude Code, Cursor, Zed, OpenAI Agents SDK, …) can call the Zeq engine directly as tools — compute, pulse, verify, lattice, shift, field-status, list-operators.

Package zeqsdk-mcp · Protocol Model Context Protocol · Transport stdio (default) or HTTP over POST /api/mcp · Precision ≤0.1 %

The MCP server is the tools side of the loop. Pair it with the Kernel Skill to give an agent both the rules (skill = system prompt) and the instruments (MCP = callable tools).

---

Start in 30 seconds — a free demo key

No signup, no card. Mint a budgeted demo key and start computing immediately. Each key is good for 100 real computes; when it's spent, mint another. (For production quota, swap in a full key from the portal.)

# 1 · mint a demo key  →  { "key": "zeq_ak_demo_…", "computeBudget": 100 }
curl -sX POST https://zeqapi.com/api/demo-key/mint

# 2 · call the kernel through the HTTP MCP bridge with that key
curl -sX POST https://zeqapi.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer zeq_ak_demo_…' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": { "name": "zeq_compute", "arguments": {
      "operators": ["KO42", "NM21"],
      "inputs": { "m1": 5.972e24, "m2": 1000, "r": 6.78e6 }
    } }
  }'
# → { "value": 8670.94, "unit": "N", "operator_id": "NM21", "zeqProof": "…", … }

Point any MCP client at the same key (see Client configs below) and the Zeq tools appear instantly. When the budget is exhausted the kernel returns 429 DAILY_LIMIT_EXCEEDED — POST /api/demo-key/mint again for a fresh key, or get a full key for production quota.

The mint endpoint is the same on every Zeq node — it's served from this domain, by this fork's own SDK. No traffic leaves the machine you're reading this on.

---

Install

As a stdio server (recommended for desktop clients)

npm install -g zeqsdk-mcp
zeqsdk-mcp                 # stdio transport, ready for any MCP client

Or via npx without installing:

npx -y zeqsdk-mcp

As an HTTP endpoint (already live on every Zeq domain)

Every Zeq node exposes the MCP bridge at:

POST https://zeqapi.com/api/mcp
Content-Type: application/json

This means MCP clients that speak HTTP (or the JSON-RPC body MCP uses) can talk to a hosted Zeq node directly, no local install. Useful for serverless agents or web clients that can't shell out.

---

Tools exposed

The server exposes nine tools mirroring the live /api/zeq/* and /api/framework/* surface. Every tool returns the same JSON envelope as the corresponding REST endpoint, so code written against the API composes identically through MCP.

Tool	Purpose	Auth
zeq_compute	Dispatch operators + inputs through the Master Equation (textbook-formula path). Returns { value, unit, equations[], master_sum, zeqState, compliance, zeqProof }	Bearer zeq_ak_*
zeq_solve	Run the master-equation ODE on a single body. Returns trajectory + register dump (period, frequency, K/U energies, momentum, angular-momentum proxy) + functional energy E = P_φ · Z(M, R, δ, C, X). Strictly numerical/categorical inputs — no string parsing.	Bearer
zeq_multibody	Vector master equation: N coupled φ_i(t) trajectories with pairwise inverse-square coupling. Returns per-body register dumps + pairwise force/separation summaries for all N·(N−1)/2 pairs. Sun-Earth-Moon style.	Bearer (N tokens)
zeq_pulse	Live HulyaPulse snapshot — { zeqond, phase, pulseHz, R_t, timeToNextZeqond }	public
zeq_list_operators	Query the full operator catalogue (1,500+ catalogued operators across QM, NM, GR, CS, awareness)	public
zeq_verify	Verify a Zeq-signed proof envelope against the registry — recomputes HMAC, checks zeqond freshness	public
zeq_lattice	Multi-operator lattice computation (parallel field evaluation)	Bearer
zeq_shift	Trigger a metric shift when zeqond variance > 0.0091 — re-aligns KO42 before returning	Bearer
zeq_field_status	Live field state — current operator phase, drift, integrity	public

zeq_compute schema

{
  "name": "zeq_compute",
  "description": "Run a Zeq computation through KO42 + selected operators.",
  "inputSchema": {
    "type": "object",
    "required": ["operators", "inputs"],
    "properties": {
      "operators": {
        "type": "array",
        "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]{1,31}$" },
        "description": "Operator IDs. Index 0 MUST be KO42."
      },
      "inputs": {
        "type": "object",
        "description": "Physical inputs as named scalars (m=mass kg, v=velocity m/s, etc.)"
      },
      "domain": { "type": "string", "description": "Optional hint: 'cross', 'quantum', 'relativistic', etc." }
    }
  }
}

zeq_solve schema

{
  "name": "zeq_solve",
  "description": "Run the HULYAS master equation on a single body. Returns trajectory + register dump + functional energy.",
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt":     { "type": "string", "description": "Label only — never read by math." },
      "mass":       { "type": "number" },
      "location":   { "type": "string", "enum": ["earth", "mars", "moon", "jupiter", "sun"] },
      "medium":     { "type": "string", "enum": ["air", "water", "vacuum"] },
      "object":     { "type": "string" },
      "koSettings": { "type": "object", "additionalProperties": { "type": "number" } },
      "alpha":      { "type": "number" },
      "beta":       { "type": "number" },
      "tMax":       { "type": "number" },
      "dt":         { "type": "number" },
      "useOperatorModules": { "type": "boolean" },
      "normalizeOperators": { "type": "boolean" },
      "coreOnly":           { "type": "boolean" },
      "referenceMode":      { "type": "string", "enum": ["free-fall", "shm", "model"] }
    }
  }
}

The text response includes the register dump's headline fields (period_s, frequency_Hz, freq_ratio_fH, energy_K_mean / U_mean / total, momentum_final, angular_proxy_mean) plus the functional-energy decomposition (P_φ, Z, M, R, δ, C, X). For the full JSON shape, see POST /api/framework/solve.

zeq_multibody schema

{
  "name": "zeq_multibody",
  "description": "Vector master equation: N coupled φ_i(t) fields with pairwise coupling.",
  "inputSchema": {
    "type": "object",
    "required": ["prompt", "bodies"],
    "properties": {
      "prompt": { "type": "string" },
      "bodies": {
        "type": "array",
        "minItems": 2,
        "maxItems": 16,
        "items": {
          "type": "object",
          "required": ["mass"],
          "properties": {
            "mass":     { "type": "number" },
            "location": { "type": "string" },
            "medium":   { "type": "string" },
            "object":   { "type": "string" },
            "phi0":     { "type": "number" },
            "dphi0":    { "type": "number" }
          }
        }
      },
      "koSettings":       { "type": "object", "additionalProperties": { "type": "number" } },
      "pairwiseCoupling": { "type": "number", "description": "γ. Default 0.05." },
      "pairwiseSoftening":{ "type": "number", "description": "ε². Default 1e-6." },
      "useOperatorModules": { "type": "boolean" },
      "coreOnly":           { "type": "boolean" }
    }
  }
}

Quota cost: N tokens (one per body). The text response includes per-body register-dump headlines plus pairwise force/separation summaries for all N·(N−1)/2 pairs. Full JSON shape at POST /api/framework/multibody.

zeq_pulse schema

No inputs. Returns:

{
  "ok": true,
  "zeqond": 2287605139,
  "phase": 0.412,
  "pulseHz": 1.287,
  "alpha_K": 0.00129,
  "R_t": 1.000532,
  "timeToNextZeqond": 0.456
}

---

Real call examples

Through Claude Desktop (stdio)

Once configured (see below), you can ask Claude:

"Compute the binding energy of helium-4 using KO42 and the nuclear binding-energy operator."

Claude routes through zeq_compute:

{
  "operators": ["KO42", "QM10"],
  "inputs": { "Z": 2, "N": 2, "A": 4, "B_per_A": 7.07e6 },
  "domain": "nuclear"
}

…and gets back the full envelope (value, unit, master_sum, zeqProof, the 13-standard compliance map, etc.).

Through HTTP MCP bridge (POST /api/mcp)

curl -sX POST https://zeqapi.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer zeq_ak_…' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "zeq_compute",
      "arguments": {
        "operators": ["KO42", "NM23"],
        "inputs": { "m": 5, "v": 10 }
      }
    }
  }'

Returns the standard JSON-RPC envelope with the compute result wrapped in result.content[0].text (per the MCP spec).

Master-equation solve through MCP (zeq_solve)

curl -sX POST https://zeqapi.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer zeq_ak_…' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "zeq_solve",
      "arguments": {
        "prompt":     "feather drop",
        "mass":       1e-4,
        "location":   "earth",
        "medium":     "air",
        "koSettings": { "KO42": 1.0 }
      }
    }
  }'

Response text excerpt:

Master Equation Solve — feather drop on earth  [mode: auto-α]
─────────────────────────────────────────────────────────────
errorPct        : 0.0019 %
energy (K+U)    : 1.3239
functionalEnergy: 20895.43  (E = P_φ · Z)
  P_φ           = 20.828
  Z             = 1003.5

Register dump
─────────────
  phi_final          = -9.2295
  zeroCrossings      = 4
  period_s           = 2.5
  frequency_Hz       = 0.4  (×0.311 of 1.287 Hz)
  energy_K_mean      = 314728.36
  energy_U_mean      = 36605.80
  momentum_final     = 8745.74
  angular_proxy_mean = -10659.54

Multi-body Sun-Earth-Moon through MCP (zeq_multibody)

curl -sX POST https://zeqapi.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer zeq_ak_…' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "zeq_multibody",
      "arguments": {
        "prompt": "sun-earth-moon",
        "bodies": [
          { "mass": 1.989e30, "location": "sun",   "object": "sun"   },
          { "mass": 5.972e24, "location": "earth", "object": "earth" },
          { "mass": 7.342e22, "location": "moon",  "object": "moon"  }
        ],
        "koSettings": { "KO42": 1.0, "NM21": 0.5, "GR35": 0.3 }
      }
    }
  }'

Returns per-body register dumps for sun / earth / moon plus 3 pairwise summaries (sun-earth, sun-moon, earth-moon).

Listing operators

curl -sX POST https://zeqapi.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc":"2.0", "id":1, "method":"tools/call",
       "params": { "name":"zeq_list_operators", "arguments":{} } }'

Returns all 1,500+ catalogued operators with id, name, domain, equation. Filter client-side for the domain you need.

Live pulse (no auth)

curl -sX POST https://zeqapi.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc":"2.0", "id":1, "method":"tools/call",
       "params": { "name":"zeq_pulse", "arguments":{} } }'

---

Client configs

Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zeq": {
      "command": "npx",
      "args": ["-y", "zeqsdk-mcp"],
      "env": {
        "ZEQ_API_URL": "https://zeqapi.com",
        "ZEQ_API_KEY": "zeq_ak_…"
      }
    }
  }
}

Restart Claude Desktop. The seven Zeq tools appear in the tool palette.

Cursor

Settings → MCP → add server. Same JSON block as above.

Zed

~/.config/zed/settings.json:

{
  "context_servers": {
    "zeq": {
      "command": { "path": "npx", "args": ["-y", "zeqsdk-mcp"], "env": {} }
    }
  }
}

OpenAI Agents SDK

Use the HTTP bridge — no stdio needed:

from openai_agents import Agent, MCPHttpClient

zeq = MCPHttpClient(
    url="https://zeqapi.com/api/mcp",
    headers={"Authorization": f"Bearer {ZEQ_API_KEY}"},
)
agent = Agent(name="zeq-physicist", tools=zeq.tools())

---

Pair with the Kernel Skill

Tools alone aren't enough — the agent also needs the protocol of how to use them. That's what the Kernel Skill provides.

Together:

1. Skill loaded as system prompt → mandates KO42, 7-step protocol, cross-domain experiments, side-by-side comparison
2. MCP server exposes the actual zeq_compute tool the skill tells the agent to call

Without the skill, an agent connected only via MCP will call zeq_compute correctly but might frame the result weakly ("here's the answer"). With both, it produces a full physics report:

Standard physics:  KE = ½mv² = 250 J
Zeq result:        R_t = 1.000532, phase = 0.412, zeqond = 2287605139
                   equations[]:
                     KO42: ds² = g_μν dx^μ dx^ν + α sin(2π·1.287·t) dt²
                     NM23: K = ½mv² with m=5 kg, v=10 m/s → 250 J
                   master_sum: { ground_state: 7.5, modulation: 0.00284, total: 7.503 }
                   zeqProof: 1f4b6a147c0024b91e5d331219e6c12e…
What Zeq adds:     Phase-locked timestamp + HMAC-signed receipt + 13-standard compliance envelope

Install both with one snippet:

# Skill — tells the LLM what to do
curl -sL https://zeqapi.com/api/kernel/skill.md \
  -o ~/.claude/skills/zeq-os-mi-kernel/SKILL.md

# MCP — gives the LLM the tools to do it
npm install -g zeqsdk-mcp

---

Self-hosted

Point the MCP server at your own Zeq node by setting ZEQ_API_URL:

{
  "env": {
    "ZEQ_API_URL": "https://your-zeq-node.example.com",
    "ZEQ_API_KEY": "zeq_ak_…"
  }
}

Every tool now routes compute through your node. Useful when you've spun up a private Zeq state machine for a regulated workload (HIPAA, GDPR Art 30, FedRAMP) and don't want traffic touching the public network.

---

Troubleshooting

Tool calls return unauthorized The tool needs a Bearer token. Check ZEQ_API_KEY in the MCP server's env, or re-mint at /state/admin/site/.

zeq_pulse returns weird zeqond values Either your local clock is off (zeqond = floor(unix_seconds / 0.777)) or you're hitting a stale CDN edge. Hit the live pulse directly: curl -s https://zeqapi.com/api/zeq/pulse.

MCP server hangs on startup First-run npm install can take a moment. Check ~/.npm/_logs/ for the actual error. The stdio transport doesn't print to a UI, so log files are your friend.

Want to see what the agent is actually sending? Set MCP_DEBUG=1 in the server env. Every JSON-RPC call gets logged to stderr.

Result envelope missing equations[] or master_sum The response shape is enforced server-side by the kernel — if those fields are missing, you've hit a stale build of zeqsdk-mcp. Update: npm install -g zeqsdk-mcp@latest.

---

See also

• Kernel Skill — the rules side of the same loop
• /api/mcp — the HTTP bridge endpoint
• /api/zeq/compute — the underlying compute route
• Operators — what zeq_list_operators returns
• TypeScript SDK · Python SDK — REST clients if you'd rather not go through MCP
• Self-hosting — bring up your own Zeq node + MCP bridge

DOI · 10.5281/zenodo.18158152 (Zeq Paper) · 10.5281/zenodo.15825138 (Framework)

---

Middleware active. Kernel on the 1.287 Hz HulyaPulse. Awaiting next Zeqond.