# @spideriq/mcp-gate

MCP server for the SpiderGate LLM gateway — completions, models, usage, traces, providers, model catalog.

## Install

### Install this exact pair

SpiderIQ ships two artifacts that must agree — the server and the skill that names its
tools. A pinned skill against a floating server (or the reverse) gives you a mismatched
pair, and the failure looks like a missing feature.

```
@spideriq/mcp-gate        1.15.0
@spideriq/gateway-skills  0.14.0
```

Server 1.15.0 adds `gate_recipes` (which recipes your keys run, and which key to add next)
beside the five setup tools (`gate_onboarding_status`, `gate_onboarding_update`,
`gate_provider_guide`, `gate_add_key`, `gate_invite_contributor`). Skill 0.14.0 teaches all
six in its `key-setup` skill; use the two together.

## Configure

**Pin the version:**

```json
{
  "mcpServers": {
    "spideriq-gate": {
      "command": "npx",
      "args": ["-y", "@spideriq/mcp-gate@1.15.1"],
      "env": {
        "SPIDERIQ_WORKSPACE": "cli_…",
        "npm_config_registry": "https://npm.spideriq.ai"
      }
    }
  }
}
```

> ⛔ **Do not `npm install -g @spideriq/mcp-gate`.** A global install wins over the spec in
> your config, so your pin looks applied and nothing changes — and there is no version in
> your own config to inspect. If you have one: `npm rm -g @spideriq/mcp-gate`.

This slice ships 38 tools, so it does not need facade mode — that is the kitchen-sink
`@spideriq/mcp` concern.

## Which tenant will this write to?

Resolution order — first hit wins. Every response reports which rung won as `_tenancy.via`.

| # | Source | How |
|---|--------|-----|
| 1 | explicit | `workspace: "cli_…"` argument on the call — **always wins, works per-call** |
| 2 | environment | `SPIDERIQ_WORKSPACE=cli_…` |
| 3 | binding | a `spideriq.json` in cwd or an ancestor (`SPIDERIQ_WORKSPACE_CWD` overrides where we look) |
| 4 | sole credential | automatic when exactly one is stored — reported as `via: "sole-credential"`, never silent |
| 5 | — | **REFUSED.** With several tenants and no binding we do not guess. The error carries `retry_with` — merge it into your retry. |

**Running an agency / multiple clients?** Pass `workspace` on every call. `cwd` is a
per-process fact; tenancy is a per-call fact, so one session can drive many tenants
with no `cd`, restart, or reconfiguration.

```js
content_list_pages({ workspace: "cli_clientA" })
content_create_page({ workspace: "cli_clientB", title: "…" })
```

> ⚠️ **Some IDEs spawn MCP servers with `cwd=/`** (Antigravity does). Nothing
> cwd-derived is reachable from there, so set `SPIDERIQ_WORKSPACE` or
> `SPIDERIQ_WORKSPACE_CWD` in the server's `env` block, or pass `workspace` per call.

Lost? Call `get_auth_status({topic:"tenancy"})` — it returns the active tenant, why it
was chosen, every workspace you can reach, and how to switch.

## Upgrading

```
SpiderIQ update — 2026-10-24

Paste to your agent:

  Update my SpiderIQ gate MCP slice to 1.15.1.
  In .mcp.json set: "args": ["-y", "@spideriq/mcp-gate@1.15.1"]
  Keep the existing "env" block as-is.
  First check: npm ls -g --depth=0 | grep @spideriq/mcp-gate — if it is installed
  globally, remove it (npm rm -g @spideriq/mcp-gate); a global install silently
  overrides the pin.
  Restart the session, then call get_auth_status to confirm.

What changed: no tool changes. It now depends on zod 4 (zod 3 carries a high
advisory with no fix), so npm audit finds nothing high.
```