# שימוש ב-API עם CKE 2.0 וכלים

> מקבלים מפתח, קוראים ל-/v1 ל-inference, מחברים את ה-MCP ל-CKE 2.0 ולכלי המחקר, ואז משתמשים בכל כלי.


ה-API עונה עם המודל. שרת ה-MCP מוסיף את CKE 2.0 ואת הכלים. המדריך הזה עובר על שניהם, מקצה לקצה. אם רוצים את הגרסה הקצרה של הסיבה שהם נפרדים, קוראים קודם את [API מול MCP](/he/mcp/overview).

## 1. מקבלים מפתח API

1. פותחים חשבון ב-[notholy.com/signup](https://notholy.com/en/signup) ומאשרים את האימייל.
2. מוסיפים קרדיט ב-**Billing**. סכום ההפקדה המינימלי מופיע באותו עמוד.
3. פותחים **API keys** ויוצרים מפתח. הוא מתחיל ב-`nh_live_` ומוצג פעם אחת.

מפתח אחד עובד גם ב-API וגם בשרת ה-MCP. מייצאים אותו:

```bash
export NOTHOLY_API_KEY="nh_live_..."
```

## 2. קוראים ל-/v1 ל-inference

זה המודל הגולמי: בלי שליפת מידע, בלי כלים, רק התשובה.

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

המודל עונה מהמשקלים של עצמו. אם שואלים אותו מה ה-CVSS של CVE חדש, הוא יכול רק לנחש, כי כאן אין לו חיפוש. את זה שרת ה-MCP פותר.

## 3. מחברים את ה-MCP ל-CKE 2.0 ולכלים

השרת מדבר MCP על Streamable HTTP בכתובת `https://api.notholy.com/mcp`. שולחים את אותו מפתח ב-`Authorization: Bearer`. בוחרים את הלקוח.

### Claude Code

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

או דרך קובץ הגדרות, ב-`.mcp.json` או ב-`~/.claude.json`:

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

### Cursor

מוסיפים את השרת ל-`.cursor/mcp.json` בפרויקט (או ל-`~/.cursor/mcp.json` לכל הפרויקטים):

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

### Claude Desktop

Claude Desktop קורא את `mcpServers` מקובץ ההגדרות שלו (**Settings → Developer → Edit Config**). הוא מתחבר לשרת מרוחק דרך `mcp-remote`:

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

מפעילים מחדש את Claude Desktop. הכלים של `notholy` מופיעים בתפריט הכלים.

### הקוד שלכם (MCP SDK)

כל ספריית לקוח של MCP מתאימה. מכוונים את תעבורת Streamable HTTP שלה אל הכתובת ומגדירים את הכותרת.

```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 גולמי

השרת הוא JSON-RPC 2.0 פשוט על HTTP, ולכן curl מספיק כדי להציג את רשימת הכלים או לקרוא לאחד מהם.

```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. משתמשים בכלים

כל קריאה לכלי היא הודעת `tools/call`. התשובה נושאת שני עותקים של התוצאה: `content[0].text` (עם שורת קידומת שמסמנת אותה כמידע חיצוני לא מהימן) ו-`structuredContent.data` (האובייקט אחרי פענוח). הדוגמאות למטה מציגות `structuredContent.data` מקוצר.

### kb_search: חיפוש ב-CKE 2.0

מחפש בבסיס הידע המאורגן של האבטחה. אפשר לסנן לפי `domain` (`web`, `api`, `mobile`, `offensive`, `tools`, `cloud`, `ir`, `attack`), `source` או `tool`. כל תוצאה נושאת את רישיון המקור ו-`id` של המסמך עבור `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: פתיחת מסמך

קורא מסמך אחד של CKE 2.0 לפי `id` (מתוך `kb_search`), בעימוד לפי קטעים עם `from` ו-`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: רשומת CVE אחת

הרשומה המאוחדת למזהה CVE: תיאור, CVSS, EPSS, סטטוס ב-CISA KEV, מוצרים מושפעים והפניות.

```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: חיפוש CVEs

חיפוש לפי טקסט, ספק או CWE, עם סינון לפי `min_cvss`, `min_epss` ו-`kev`.

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

### שאר הכלים בשורה אחת

הרשימה המלאה עם המגבלות ב[שרת MCP מרוחק](/he/mcp/remote). שאר הכלים בנויים באותה צורה:

- `advisory_query` — התרעות לחבילה: `{"name": "lodash", "ecosystem": "npm", "version": "4.17.15"}`.
- `web_search` — הרשת הציבורית: `{"query": "log4shell detection"}`.
- `read_url` — דף ציבורי אחד דרך הקורא המוגן מ-SSRF: `{"url": "https://example.com/advisory"}`.
- `analyze_file` — ניתוח סטטי. בשרת מרוחק מעבירים `name` ו-`content_base64`: `{"name": "handler.js", "content_base64": "..."}`.
- `ip_info`, `domain_info`, `asn_lookup`, `site_check`, `breach_check` — מודיעין רשת פסיבי.
- `port_scan` — הכלי הפעיל היחיד. סורקים רק hosts שמותר לכם לבדוק.
- `darkweb_search` — חיפוש באינדקס של Tor. קוראים לו רק כשהמשתמש מבקש חיפוש ב-dark web.
- `skills_search`, `skill_get`, `skill_invoke` — רישום הסקילים.

## קרדיט ומגבלות

הכלים דורשים קרדיט בחשבון. בלי קרדיט, נתיבי המחקר מחזירים `402 insufficient_credits`, וקריאה לכלי מחזירה את ההודעה הזו במקום תוצאה, עם קישור לדף החיוב. שרת ה-MCP עדיין מתחבר ומציג את רשימת הכלים. הקריאות נספרות במגבלה של 120 בקשות לדקה של נתיבי המחקר. Inference ב-`/v1` מחויב לפי טוקן, וכלי המחקר לא משתמשים בטוקנים.

## הבא

- [שרת MCP מרוחק](/he/mcp/remote): רשימת הכלים המלאה והמגבלות
- [שרת MCP מקומי](/he/mcp/local): הרצת הכלים דרך ה-CLI על stdio
- [API המחקר](/he/api/research): אותם נתונים כנתיבי HTTP פשוטים
