# Use the API with CKE 2.0 and tools

> Get a key, call /v1 for inference, connect the MCP for CKE 2.0 and the research tools, then use each tool.


The API answers with the model. The MCP server adds CKE 2.0 and the tools. This guide does both, end to end. If you want the short version of why they are separate, read [API vs MCP](/en/mcp/overview) first.

## 1. Get an API key

1. Create an account at [notholy.com/signup](https://notholy.com/en/signup) and confirm your e-mail.
2. Add credits in **Billing**. The minimum deposit is on that page.
3. Open **API keys** and create a key. It starts with `nh_live_` and is shown once.

One key works for both the API and the MCP server. Export it:

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

## 2. Call /v1 for inference

This is the raw model: no retrieval, no tools, just the answer.

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

The model answers from its own weights. Ask it for the CVSS of a fresh CVE and it can only guess, because it has no lookup here. That is what the MCP server fixes.

## 3. Connect the MCP for CKE 2.0 and the tools

The server speaks MCP over Streamable HTTP at `https://api.notholy.com/mcp`. Send the same key in `Authorization: Bearer`. Pick your client.

### Claude Code

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

Or by configuration, in `.mcp.json` or `~/.claude.json`:

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

### Cursor

Add the server to `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for every project):

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

### Claude Desktop

Claude Desktop reads `mcpServers` from its config file (**Settings → Developer → Edit Config**). It bridges a remote server with `mcp-remote`:

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

Restart Claude Desktop. The `notholy` tools appear in the tools menu.

### Your own code (MCP SDK)

Any MCP client library works. Point its Streamable HTTP transport at the URL and set the header.

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

### Raw JSON-RPC

The server is plain JSON-RPC 2.0 over HTTP, so curl is enough to list the tools or call one.

```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. Use the tools

Every tool call is a `tools/call` message. The reply carries two copies of the result: `content[0].text` (prefixed with a line that marks it as untrusted outside data) and `structuredContent.data` (the parsed object). The examples below show trimmed `structuredContent.data`.

### kb_search: search CKE 2.0

Searches the curated security knowledge base. Filter by `domain` (`web`, `api`, `mobile`, `offensive`, `tools`, `cloud`, `ir`, `attack`), `source` or `tool`. Each hit carries its source licence and a document `id` for `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: open a document

Reads one CKE 2.0 document by `id` (from `kb_search`), paginated by section with `from` and `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: one CVE record

The consolidated record for a CVE id: description, CVSS, EPSS, CISA KEV status, affected products and references.

```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: search CVEs

Search by text, vendor or CWE, filtered by `min_cvss`, `min_epss` and `kev`.

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

### Other tools in one line

See [Remote MCP server](/en/mcp/remote) for the full list with limits. The rest take the same shape:

- `advisory_query` — advisories for a package: `{"name": "lodash", "ecosystem": "npm", "version": "4.17.15"}`.
- `web_search` — public web: `{"query": "log4shell detection"}`.
- `read_url` — one public page through the SSRF-protected reader: `{"url": "https://example.com/advisory"}`.
- `analyze_file` — static analysis; remotely pass `name` and `content_base64`: `{"name": "handler.js", "content_base64": "..."}`.
- `ip_info`, `domain_info`, `asn_lookup`, `site_check`, `breach_check` — passive network intel.
- `port_scan` — the one active tool; only scan hosts you may test.
- `darkweb_search` — Tor index search; call it only when the user asks for a dark web search.
- `skills_search`, `skill_get`, `skill_invoke` — the skills registry.

## Credit and limits

The tools need credit on your account. Without it, the research routes answer `402 insufficient_credits`, and a tool call returns that message instead of a result, with a link to billing. The MCP server still connects and lists its tools. Calls count against the 120 requests per minute of the research routes. Inference on `/v1` is billed per token; the research tools do not use tokens.

## Next

- [Remote MCP server](/en/mcp/remote): the full tool list and limits
- [Local MCP server](/en/mcp/local): run the tools through the CLI over stdio
- [Research API](/en/api/research): the same data as plain HTTP routes
