Vai al contenuto
NotHolyDocs

MCP

Usa l'API con CKE 2.0 e gli strumenti

Ottieni una chiave, chiama /v1 per l'inferenza, collega l'MCP per CKE 2.0 e gli strumenti di ricerca, poi usa ogni strumento.

Vedi in Markdown

L'API risponde con il modello. Il server MCP aggiunge CKE 2.0 e gli strumenti. Questa guida fa entrambe le cose, dall'inizio alla fine. Se vuoi la versione breve del perché sono separati, leggi prima API e MCP.

1. Ottieni una chiave API

  1. Crea un account su notholy.com/signup e conferma la tua email.
  2. Aggiungi credito in Fatturazione. Il deposito minimo è su quella pagina.
  3. Apri Chiavi API e crea una chiave. Inizia con nh_live_ e viene mostrata una sola volta.

Una chiave vale sia per l'API sia per il server MCP. Esportala:

Shell
export NOTHOLY_API_KEY="nh_live_..."

2. Chiama /v1 per l'inferenza

È il modello grezzo: niente recupero, niente strumenti, solo la risposta.

curl https://api.notholy.com/v1/chat/completions \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "notholy-specter", "messages": [{"role": "user", "content": "Explain IDOR in two sentences."}]}'

Il modello risponde dai propri pesi. Se gli chiedi il CVSS di una CVE appena uscita, può solo tirare a indovinare, perché qui non ha nessuna consultazione. È quello che risolve il server MCP.

3. Collega l'MCP per CKE 2.0 e gli strumenti

Il server parla MCP via Streamable HTTP su https://api.notholy.com/mcp. Invia la stessa chiave in Authorization: Bearer. Scegli il tuo client.

Claude Code

Shell
claude mcp add --transport http notholy https://api.notholy.com/mcp --header "Authorization: Bearer $NOTHOLY_API_KEY"

Oppure da configurazione, in .mcp.json o ~/.claude.json:

JSON
{"mcpServers": {"notholy": {"type": "http", "url": "https://api.notholy.com/mcp", "headers": {"Authorization": "Bearer ${NOTHOLY_API_KEY}"}}}}

Cursor

Aggiungi il server a .cursor/mcp.json nel progetto (o a ~/.cursor/mcp.json per tutti i progetti):

JSON
{"mcpServers": {"notholy": {"url": "https://api.notholy.com/mcp", "headers": {"Authorization": "Bearer nh_live_..."}}}}

Claude Desktop

Claude Desktop legge mcpServers dal suo file di configurazione (Settings → Developer → Edit Config). Collega un server remoto con mcp-remote:

JSON
{"mcpServers": {"notholy": {"command": "npx", "args": ["-y", "mcp-remote", "https://api.notholy.com/mcp", "--header", "Authorization: Bearer nh_live_..."]}}}

Riavvia Claude Desktop. Gli strumenti notholy compaiono nel menu degli strumenti.

Il tuo codice (SDK MCP)

Funziona qualsiasi libreria client MCP. Punta il suo trasporto Streamable HTTP sull'URL e imposta l'intestazione.

import os, asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = "https://api.notholy.com/mcp"
HEADERS = {"Authorization": f"Bearer {os.environ['NOTHOLY_API_KEY']}"}

async def main():
    async with streamablehttp_client(URL, headers=HEADERS) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            out = await session.call_tool("cve_lookup", {"id": "CVE-2021-44228"})
            print(out.structuredContent)

asyncio.run(main())

JSON-RPC grezzo

Il server è JSON-RPC 2.0 semplice su HTTP, quindi basta curl per elencare gli strumenti o chiamarne uno.

curl
curl https://api.notholy.com/mcp \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

4. Usa gli strumenti

Ogni chiamata a uno strumento è un messaggio tools/call. La risposta porta due copie del risultato: content[0].text (preceduto da una riga che lo marca come dato esterno non attendibile) e structuredContent.data (l'oggetto già analizzato). Gli esempi qui sotto mostrano structuredContent.data accorciato.

kb_search: cerca in CKE 2.0

Cerca nella base di conoscenza di sicurezza curata. Filtra per domain (web, api, mobile, offensive, tools, cloud, ir, attack), source o tool. Ogni risultato riporta la licenza della sua fonte e un id di documento per kb_read.

JSON
{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
 "params": {"name": "kb_search", "arguments": {"query": "ssrf prevention", "domain": "web", "limit": 3}}}
JSON
{"data": {"hits": [
  {"id": "owasp-cheatsheet-ssrf", "title": "SSRF Prevention Cheat Sheet", "source": "OWASP", "licence": "CC-BY-SA-4.0", "score": 0.82,
   "snippet": "Validate the host against an allow-list, resolve it, and pin the connection to the resolved IP..."}
]}}

kb_read: apri un documento

Legge un documento CKE 2.0 per id (da kb_search), paginato per sezione con from e limit.

JSON
{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
 "params": {"name": "kb_read", "arguments": {"id": "owasp-cheatsheet-ssrf", "from": 0, "limit": 2}}}
JSON
{"data": {"id": "owasp-cheatsheet-ssrf", "title": "SSRF Prevention Cheat Sheet", "source": "OWASP",
  "sections": [{"heading": "Allow-list the destination", "text": "..."}],
  "next": 2, "total": 9}}

cve_lookup: il record di una CVE

Il record consolidato di un id CVE: descrizione, CVSS, EPSS, stato CISA KEV, prodotti interessati e riferimenti.

JSON
{"jsonrpc": "2.0", "id": 4, "method": "tools/call",
 "params": {"name": "cve_lookup", "arguments": {"id": "CVE-2021-44228"}}}
JSON
{"data": {"id": "CVE-2021-44228", "cvss": {"score": 10.0, "vector": "CVSS:3.1/AV:N/AC:L/..."},
  "epss": {"score": 0.975, "percentile": 0.999}, "kev": {"listed": true, "known_ransomware": true},
  "cwe": ["CWE-502", "CWE-917"], "references": ["https://nvd.nist.gov/vuln/detail/CVE-2021-44228"]}}

cve_search: cerca CVE

Cerca per testo, vendor o CWE, filtrando con min_cvss, min_epss e kev.

JSON
{"jsonrpc": "2.0", "id": 5, "method": "tools/call",
 "params": {"name": "cve_search", "arguments": {"vendor": "apache", "cwe": "CWE-502", "kev": true, "limit": 5}}}

Altri strumenti in una riga

Vedi Server MCP remoto per l'elenco completo con i limiti. Gli altri hanno la stessa forma:

  • advisory_query — bollettini di un pacchetto: {"name": "lodash", "ecosystem": "npm", "version": "4.17.15"}.
  • web_search — web pubblico: {"query": "log4shell detection"}.
  • read_url — una pagina pubblica tramite il lettore protetto da SSRF: {"url": "https://example.com/advisory"}.
  • analyze_file — analisi statica; da remoto passa name e content_base64: {"name": "handler.js", "content_base64": "..."}.
  • ip_info, domain_info, asn_lookup, site_check, breach_check — intelligence di rete passiva.
  • port_scan — l'unico strumento attivo; scansiona solo host che puoi testare.
  • darkweb_search — ricerca nell'indice Tor; chiamalo solo quando l'utente chiede una ricerca nel dark web.
  • skills_search, skill_get, skill_invoke — il registro delle skill.

Credito e limiti

Gli strumenti richiedono credito sull'account. Senza credito, le route di ricerca rispondono 402 insufficient_credits e una chiamata a uno strumento restituisce quel messaggio al posto del risultato, con il link alla fatturazione. Il server MCP si connette comunque ed elenca i suoi strumenti. Le chiamate contano nelle 120 richieste al minuto delle route di ricerca. L'inferenza su /v1 si paga a token; gli strumenti di ricerca non usano token.

Prossimi passi