# @spideriq/mcp-media

> Atomic MCP server for **SpiderMedia** — file/video management plus the read-only per-tenant media catalog. 17 tools (8 shared + 6 file/video + 3 catalog).

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 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 SpiderMedia tools — well under the ~128-tool ceiling 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.** Media-only agents don't load content, lead-gen, email, or gateway tools.

## Install

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

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

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

**File / video (6):** `import_from_url`, `list_files`, `delete_file`, `list_videos`, `get_video_status`, `get_media_stats`. These operate on a provisioned media bucket (carried 1:1 from `@spideriq/mcp-publish`, where they still work unchanged).

**Catalog — read-only (3):** `catalog_list_assets`, `catalog_get_asset`, `catalog_search_assets`. These read the per-tenant `media_assets` DAM catalog, which spans **every** storage tier (SeaweedFS / R2 / PeerTube) and asset kind (image / video / doc) — broader than `list_files`/`list_videos`, which only see one provisioned bucket. Each accepts `format: json|yaml|md`.

> **Safety (Mux pattern):** the catalog tools are read-only. The only destructive media tool is `delete_file` (bucket-scoped, carried for back-compat). There is no catalog delete/purge tool.

## See also

- [@spideriq/mcp](https://npm.spideriq.ai/-/web/detail/@spideriq/mcp) — kitchen-sink MCP (all slices)
- [@spideriq/cli](https://npm.spideriq.ai/-/web/detail/@spideriq/cli) — `spideriq media list|get|search|upload` for humans
- [SpiderCLI docs](../../docs/services/SpiderCLI/CLAUDE.md)