Anomalia MCP

Anomalia espone un server Model Context Protocol così gli agenti di coding (Cursor, Claude e altri) possono gestire brand, post, piani, studio, SEO/GEO e blog — con lo stesso login OAuth della CLI.

Your agent
   │  stdio (local)     →  bun run mcp  /  anomalia-mcp
   │  HTTPS (remote)    →  https://mcp.anomalia.so/mcp  + Bearer
   ▼
Anomalia API  (/api/v1/*)

Niente token API statici. L'autenticazione è sempre OAuth (login nel browser o Bearer dalla sessione).

Avvio rapido

Scegli un trasporto: stdio locale è il più semplice sulla tua macchina; HTTP remoto per host cloud.

Opzione A — Stdio locale

Ideale per Cursor e altri agenti locali.

Installa Bun e clona il repo anomalia-cli (oppure installa il binario CLI così anomalia-mcp è nel PATH).

Autenticati una volta:

anomalia login
# or, after MCP is connected, call the login tool

Aggiungi alla config MCP di Cursor (serve il path assoluto con Bun):

{
  "mcpServers": {
    "anomalia": {
      "command": "bun",
      "args": ["run", "/ABS/PATH/to/anomalia-cli/mcp/stdio.ts"]
    }
  }
}

Se il binario è nel PATH dopo l'installazione:

{
  "mcpServers": {
    "anomalia": { "command": "anomalia-mcp" }
  }
}

Riavvia Cursor / ricarica MCP. Chiama list_brands, poi lavora con lo slug del brand.

File di sessione (condiviso con la CLI): ~/.config/anomalia/session.json.

Opzione B — HTTP remoto

Verifica che il server sia su:
```
curl -sS https://mcp.anomalia.so/health
```
Attendi un payload JSON di health con ok: true e mcp: "/mcp".

Config MCP di Cursor:

{
  "mcpServers": {
    "anomalia": {
      "url": "https://mcp.anomalia.so/mcp"
    }
  }
}

I client che supportano OAuth MCP (opencode, Claude Code, Cursor, l’Inspector…) si autenticano da soli: alla prima connessione aprono anomalia.so, tu autorizzi e il token resta nel client. Il 401 iniziale è l’inizio di quel handshake, non un errore.

Opzione custom — se il tuo client non supporta OAuth, passa il token a mano: Authorization: Bearer <access_token>, con l’access token Supabase che anomalia login salva in ~/.config/anomalia/session.json. Le API key statiche (anomalia_…) non sono accettate dal server remoto.

Opzione C — HTTP locale

bun install
bun run mcp:http
# → http://localhost:8787/mcp
#    http://localhost:8787/health

Auth: Bearer oppure il file di sessione locale.

Regole di auth

Contesto	Come ti autentichi
Stdio locale / HTTP locale	Tool login nel browser o anomalia login → file di sessione
HTTP remoto	OAuth 2.1 + PKCE, or `Authorization: Bearer <access_token>`
API key statica	Non supportata

Metadata della risorsa protetta: GET /.well-known/oauth-protected-resource.

Cosa chiamare per primi

list_brands — scopri gli slug dei brand
get_dashboard — panoramica del brand
list_posts con status pending_user — coda di approvazione
Preferisci tool specifici (approve_posts, edit_post, …) rispetto a chat per azioni precise

Gli id di post e articoli accettano prefissi corti non ambigui dai risultati di list (stessa regola della CLI).

Aree tool

Area	Esempi
Auth	`login`, `logout`, `whoami`, `list_brands`
Post	`list_posts`, `get_post`, `edit_post`, `approve_posts`, `regenerate_slide`, `make_video`
Piani	`get_plan`, `propose_plan`, `plan_week`, `produce_week`
Studio	`get_studio`, `add_note`, `research_competitors`
Web	`get_seo`, `get_geo`, `generate_article`, `chat`

Risoluzione problemi

Sintomo	Causa probabile	Fix
401 su /mcp	Bearer mancante o non valido sul remoto	Fai login in locale e passa l'access token, oppure usa stdio
Tool mancanti	MCP non connesso nell'host	Controlla il pannello MCP di Cursor e riavvia l'host
Auth ok in CLI ma non in MCP	Macchina diversa / nessun file di sessione	Esegui login nell'ambiente del processo MCP

Avanti

Agent skill — installa lo skill Anomalia così gli agenti sanno quando e come usare MCP o la CLI
CLI — comandi da terminale quando MCP non è disponibile
Riferimento API — endpoint REST chiamati da MCP e CLI
anomalia-cli — sorgente, mappa tool e note di sviluppo