# @spideriq/mcp-publish

> Atomic MCP server for **SpiderPublish** — the SpiderIQ content platform. Pages, posts, docs, templates, components, domains, media. ~87 tools.

Part of the SpiderIQ MCP catalog. See [@spideriq/mcp](https://npm.spideriq.ai/-/web/detail/@spideriq/mcp) for the kitchen-sink variant that includes every slice (~157 tools) and [@spideriq/cli](https://npm.spideriq.ai/-/web/detail/@spideriq/cli) for the command-line variant.


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

## Why this package

- **Focused toolset.** Only content platform tools, nothing else. Stays well under the ~128 tool limit some IDEs impose (Antigravity, some OpenAI Responses deployments).
- **Less context noise.** Fewer tool schemas injected into the LLM context means more room for actual work.
- **Product-aligned.** SpiderPublish-only customers don't see lead-gen, email, or gateway tools.

## Install

```json
{
  "mcpServers": {
    "spideriq-publish": {
      "command": "npx",
      "args": ["-y", "@spideriq/mcp-publish"],
      "env": {
        "SPIDERIQ_FORMAT": "yaml",
        "npm_config_registry": "https://npm.spideriq.ai"
      }
    }
  }
}
```

Then restart your IDE (Claude Code, Cursor, Antigravity, Windsurf).

### Mac runtimes with the ~128-tool ceiling

Antigravity / Claude Desktop / some Codex-on-Responses deployments
silently drop MCP servers whose `tools/list` exceeds ~128 entries.
Pre-2026-05-22 every team rolled their own filter proxy and dropped
different tools (the 2026-05-22 Claude Code usability report
documented an authoring session that got stuck because the local
proxy filter hid `content_create_component` /
`content_update_settings` / `template_apply_theme` / etc.).

Set `SPIDERIQ_MCP_SLICE=mac-128` in your `.mcp.json` env to opt in to
the canonical curated slice — guaranteed under the ceiling forever
with the full authoring path (pages, posts, components, settings,
themes, deploys, visual-check, forms, media) intact:

```json
{
  "mcpServers": {
    "spideriq-publish": {
      "command": "npx",
      "args": ["-y", "@spideriq/mcp-publish"],
      "env": {
        "SPIDERIQ_FORMAT": "yaml",
        "SPIDERIQ_MCP_SLICE": "mac-128",
        "npm_config_registry": "https://npm.spideriq.ai"
      }
    }
  }
}
```

Niche tools excluded from `mac-128`: directory/programmatic SEO,
playbooks, scroll-sequence helpers, marketplace admin curation,
component propagation, audit-extras. If you need any of those,
either omit `SPIDERIQ_MCP_SLICE` (full set) or switch to
`@spideriq/cli` for the command-line path.

## Authenticate

First time only — the server exposes the standard SpiderIQ PAT flow:

1. Ask the agent to call `request_access` with your admin email
2. Admin approves via email link
3. Token is saved to `~/.spideriq/credentials.json` and every subsequent call uses it

See [SpiderCLI authentication docs](../../docs/services/SpiderCLI/CLAUDE.md#pat-authentication-flow) for the full flow diagram.

## Tools included

**Shared (8):** `request_access`, `check_access_status`, `get_auth_status`, `logout`, `list_workspaces`, `health_check`, `get_queue_stats`, `get_api_info`.

**Content (~50):** pages, posts, docs, categories, tags, navigation, settings. Full CRUD + publish/unpublish + scheduled publishing.

**Templates (12):** `template_list`, `template_get`, `template_upsert`, `template_delete`, `template_apply_theme`, `template_list_themes`, `template_get_config`, `template_update_config`, `template_preview`, `template_get_help`, `content_deploy_site`, `content_deploy_status`.

**Components (9):** create/read/update/delete reusable UI components with Shadow DOM isolation, plus versioning, publish, archive.

**Domains (~5):** add domain, verify, set primary, delete, list.

**Media (~2):** upload and list media files.

Run the `template_get_help` tool for a YAML reference of every content type, Liquid filter, and block type — ~2,867 tokens, far cheaper than reading this README in a prompt.

## Version binding

The package reports a version derived from `@spideriq/core` in its handshake (currently `0.8.3` — the shared API-client version). Bug fixes to shared auth/system tools propagate via a coordinated republish of every slice + the kitchen sink.

## See also

- [@spideriq/mcp](https://npm.spideriq.ai/-/web/detail/@spideriq/mcp) — kitchen-sink MCP (all slices, ~157 tools)
- [@spideriq/cli](https://npm.spideriq.ai/-/web/detail/@spideriq/cli) — command-line tools for humans
- [SpiderCLI docs](../../docs/services/SpiderCLI/CLAUDE.md)