# Cos'è MCP?

Il **Model Context Protocol (MCP)** è uno standard aperto creato da Anthropic
(2024) che consente agli LLM di richiamare strumenti esterni in modo
strutturato. Invece di incollare la documentazione dell'API nel prompt, si
registrano gli strumenti presso il server MCP e l'LLM li richiama quando
necessario — come il function calling, ma standardizzato e indipendente dal
client.

## Server MCP di Synapse

Synapse include un server MCP ufficiale (`synapse-mcp-api` su npm) che espone
**79 strumenti** per tutte le funzionalità di Synapse:

| Categoria | Strumenti | Numero |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cron_list, cron_create, cron_delete, cron_toggle, var_list, var_get, var_set, var_delete | 8 |
| Tasks | task_list, task_get, task_create, task_update | 4 |
| Scripts | script_list, script_get, script_info, script_store, script_delete | 5 |
| Computers | computer_list, computer_get, install_code, screenshot, command_queue, command_status, commands_list, disable, delete | 9 |
| Push | vapid_public_key, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, minds_list, mind_create, mind_delete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| **Totale** | | **79+** |

## Come funziona

```
┌──────────────────┐    MCP protocol    ┌──────────────────┐    HTTP    ┌──────────┐
│  LLM Client      │ ◀─────────────────▶│  Synapse MCP     │ ─────────▶ │ Synapse  │
│ (Claude/Cursor)  │   (stdio/SSE/WS)   │  Server          │            │ API      │
└──────────────────┘                    └──────────────────┘            └──────────┘
```

1. Si configura il client LLM (Claude Desktop, Cursor, ecc.) per utilizzare il server MCP di Synapse
2. Il client avvia il server MCP (tramite `npx -y synapse-mcp-api@latest`)
3. Il server MCP si connette all'API di Synapse utilizzando la propria Mind Key
4. L'LLM vede tutti i 79 strumenti come funzioni native che può richiamare
5. Quando l'LLM deve ricordare qualcosa, richiama `memory_store` — il server MCP lo traduce in `POST /memory` su Synapse

## Trasporti

Il server MCP di Synapse supporta tre trasporti:

### stdio (locale, consigliato per desktop)

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_...",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

### HTTP/SSE (remoto, multi-tenant)

Colleghi il proprio client MCP a:

```
URL: https://synapse-mcp.schaefer.zone/sse
Headers: Authorization: Bearer YOUR_MIND_KEY
```

### WebSocket (mobile, alto volume)

```
URL: wss://synapse-mcp.schaefer.zone/ws?mind_key=YOUR_MIND_KEY
```

## Profili degli strumenti (v1.4.0)

Per ridurre il consumo di token per LLM più piccoli, il server MCP supporta
tre profili di strumenti:

| Profilo | Strumenti | Token | Ideale per |
|---------|-------|--------|----------|
| `minimal` | 8 (dispatch composito) | ~500 | LLM self-hosted con contesto ≤8k |
| `standard` | 25 (nominati) | ~2,500 | LLM di media dimensione (Claude Haiku, GPT-3.5) |
| `full` | 119 (tutti) | ~8,250 | LLM di grandi dimensioni (Claude Sonnet/Opus, GPT-4) — predefinito |

Si controlla tramite:

- Variabile d'ambiente: `MCP_PROFILE=minimal|standard|full`
- Header: `Mcp-Tool-Profile: minimal|standard|full`

## Client supportati

- [Claude Desktop](/docs/mcp/claude-desktop) — app desktop di Anthropic
- [Claude Code](/docs/mcp/claude-code) — agente di coding da terminale
- [Cursor](/docs/mcp/cursor) — IDE basato sull'AI
- [Continue.dev](/docs/mcp/continue) — assistente di coding AI open-source
- [Cline](/docs/mcp/claude-code) — estensione VS Code
- Qualsiasi client compatibile con MCP

## Perché usare MCP invece dell'API diretta?

| Approccio | Pro | Contro |
|----------|------|------|
| API diretta | Semplice, nessuno strato aggiuntivo | L'LLM deve conoscere URL, header, autenticazione |
| MCP | L'LLM vede strumenti nativi, senza dover ricordare URL | Processo server MCP aggiuntivo |

Per la maggior parte dei casi d'uso con agenti LLM, MCP è la scelta migliore
— l'LLM non deve ricordare i percorsi dell'API o i modelli di autenticazione.

## Prossimi passi

- [Configurazione di Claude Desktop](/docs/mcp/claude-desktop) — configurazione in 2 minuti
- [Configurazione di Claude Code](/docs/mcp/claude-code) — integrazione da terminale
- [Client MCP personalizzato](/docs/mcp/custom-client) — costruirne uno proprio