Saltar al contenido
NotHolyDocs

MCP

Usa la API con CKE 2.0 y herramientas

Consigue una clave, llama a /v1 para inferencia, conecta el MCP para CKE 2.0 y las herramientas de investigación, y usa cada herramienta.

Ver en Markdown

La API responde con el modelo. El servidor MCP agrega CKE 2.0 y las herramientas. Esta guía hace las dos cosas, de punta a punta. Si quieres la versión corta de por qué van separadas, lee primero API vs MCP.

1. Consigue una clave de API

  1. Crea una cuenta en notholy.com/signup y confirma tu correo.
  2. Agrega créditos en Facturación. El depósito mínimo está en esa página.
  3. Abre Claves de API y crea una clave. Empieza con nh_live_ y se muestra una sola vez.

Una clave sirve para la API y para el servidor MCP. Expórtala:

Shell
export NOTHOLY_API_KEY="nh_live_..."

2. Llama a /v1 para inferencia

Este es el modelo en bruto: sin recuperación de información, sin herramientas, solo la respuesta.

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."}]}'

El modelo responde con lo que hay en sus pesos. Si le pides el CVSS de un CVE reciente, solo puede adivinar, porque aquí no tiene consulta. Eso es lo que arregla el servidor MCP.

3. Conecta el MCP para CKE 2.0 y las herramientas

El servidor habla MCP por Streamable HTTP en https://api.notholy.com/mcp. Envía la misma clave en Authorization: Bearer. Elige tu cliente.

Claude Code

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

O por configuración, en .mcp.json o ~/.claude.json:

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

Cursor

Agrega el servidor a .cursor/mcp.json en el proyecto (o a ~/.cursor/mcp.json para todos los proyectos):

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

Claude Desktop

Claude Desktop lee mcpServers de su archivo de configuración (Settings → Developer → Edit Config). Conecta un servidor remoto con mcp-remote:

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

Reinicia Claude Desktop. Las herramientas de notholy aparecen en el menú de herramientas.

Tu propio código (SDK de MCP)

Sirve cualquier biblioteca cliente de MCP. Apunta su transporte Streamable HTTP a la URL y define la cabecera.

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 directo

El servidor es JSON-RPC 2.0 simple sobre HTTP, así que curl basta para listar las herramientas o llamar a una.

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 las herramientas

Cada llamada a una herramienta es un mensaje tools/call. La respuesta trae dos copias del resultado: content[0].text (con una línea inicial que lo marca como datos externos no confiables) y structuredContent.data (el objeto ya interpretado). Los ejemplos de abajo muestran un structuredContent.data recortado.

kb_search: busca en CKE 2.0

Busca en la base de conocimiento de seguridad seleccionada. Filtra por domain (web, api, mobile, offensive, tools, cloud, ir, attack), source o tool. Cada resultado trae la licencia de su fuente y un id de documento para 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: abre un documento

Lee un documento de CKE 2.0 por id (de kb_search), paginado por sección con from y 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: un registro de CVE

El registro consolidado de un id de CVE: descripción, CVSS, EPSS, estado en CISA KEV, productos afectados y referencias.

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: busca CVEs

Busca por texto, proveedor o CWE, filtrado por min_cvss, min_epss y kev.

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

Las demás herramientas en una línea

Mira el servidor MCP remoto para la lista completa con límites. El resto tiene la misma forma:

  • advisory_query — advisories de un paquete: {"name": "lodash", "ecosystem": "npm", "version": "4.17.15"}.
  • web_search — web pública: {"query": "log4shell detection"}.
  • read_url — una página pública por el lector protegido contra SSRF: {"url": "https://example.com/advisory"}.
  • analyze_file — análisis estático; en remoto pasa name y content_base64: {"name": "handler.js", "content_base64": "..."}.
  • ip_info, domain_info, asn_lookup, site_check, breach_check — inteligencia de red pasiva.
  • port_scan — la única herramienta activa; escanea solo hosts que puedas probar.
  • darkweb_search — búsqueda en el índice de Tor; llámala solo cuando el usuario pida una búsqueda en la dark web.
  • skills_search, skill_get, skill_invoke — el registro de skills.

Crédito y límites

Las herramientas necesitan crédito en la cuenta. Sin crédito, las rutas de investigación responden 402 insufficient_credits, y una llamada a una herramienta devuelve ese mensaje en lugar del resultado, con un enlace a facturación. El servidor MCP sigue conectando y listando sus herramientas. Las llamadas cuentan en el límite de 120 solicitudes por minuto de las rutas de investigación. La inferencia en /v1 se cobra por token; las herramientas de investigación no usan tokens.

Siguientes pasos