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


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](/es/mcp/overview).

## 1. Consigue una clave de API

1. Crea una cuenta en [notholy.com/signup](https://notholy.com/es/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:

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

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

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.notholy.com/v1", api_key=os.environ["NOTHOLY_API_KEY"])

r = client.chat.completions.create(
    model="notholy-specter",
    messages=[{"role": "user", "content": "Explain IDOR in two sentences."}],
)
print(r.choices[0].message.content)
```

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

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

```python
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())
```

```ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.notholy.com/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.NOTHOLY_API_KEY}` } },
});
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools.tools.map((t) => t.name));

const out = await client.callTool({ name: 'cve_lookup', arguments: { id: 'CVE-2021-44228' } });
console.log(out.structuredContent);
```

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

```bash
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](/es/mcp/remote) 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

- [Servidor MCP remoto](/es/mcp/remote): la lista completa de herramientas y límites
- [Servidor MCP local](/es/mcp/local): ejecuta las herramientas por el CLI sobre stdio
- [API de investigación](/es/api/research): los mismos datos como rutas HTTP simples
