Content
# onlinecybertools-mcp-server
MCP (Model Context Protocol) server that lets AI agents — Claude Code, Codex,
Cursor, Continue, etc. — use the
[Online Cyber Tools](https://onlinecybertools.com) catalogue as a set of
native MCP tools.
## What it exposes
- One MCP tool per documented MCP-compatible `/api/tools/{category}/{tool}`
operation. `POST` tools use their JSON request-body schema; compatible
`GET` tools use OpenAPI query/path parameters. Schemas are taken straight
from the site's OpenAPI 3.1 spec at `/api/openapi.json`, so agents get
per-tool argument validation. When the spec declares them, a tool also
carries MCP `annotations` (`title` plus `readOnlyHint` /
`destructiveHint` / `idempotentHint`, sourced from `x-mcp-annotations`)
and an `outputSchema` (the inline `200` response object schema).
- A `search` meta-tool that performs the same keyword search humans use,
backed by `GET /api/tools/search?q=...`.
- A `describe_tool` meta-tool that fetches the long page guidance, source
links, page URL, API endpoint, and SEO description from
`GET /api/mcp/tool-docs/{tool_id}`. It accepts either a menu ID such as
`ping` or an MCP tool name such as `network_ping`.
- A `report_bug` meta-tool that files a structured bug report against
`POST /api/agent/bug-report` (hard rate-limited).
Calls are proxied to the live HTTP API — no algorithm is re-implemented here.
That guarantees agents see whatever the deployed site does.
Generated tool descriptions are the operation's OpenAPI summary + description,
nothing else — no menu-ID prefix or `describe_tool` pointer (both read as
noise to a calling agent). The `describe_tool` meta-tool is still available
for agents that want the full page guidance on demand.
<!-- TOOLS:BEGIN (auto-generated by `php bin/console mcp:tools-doc`; do not edit by hand) -->
## Tools
This server exposes **279 tools** across 15 categories:
Encoding/Decoding, Binary/Text Conversion, Cryptography & Hashing, Web Dev Utilities, Text Utilities, OSINT Tools, Networking Tools, Security Tools, SEO Tools, Linux Tools, Date & Time, Math & Calculators, Data Tools, File Tools, Reverse Engineering.
- **Full list (this repo):** [`TOOLS.md`](./TOOLS.md) — every tool, grouped by category.
- **Live catalogue:** <https://onlinecybertools.com/#browse-the-full-inventory>
- **Machine-readable spec:** <https://onlinecybertools.com/api/openapi.json>
- **Pick a subset / build a config:** <https://onlinecybertools.com/integrations/mcp-plugin-builder>
This section and `TOOLS.md` are auto-generated from the live menu on
every release, so the count and list never drift.
<!-- TOOLS:END -->
## Quick start
The package is published on npm as
[`onlinecybertools-mcp-server`](https://www.npmjs.com/package/onlinecybertools-mcp-server),
so any MCP client can launch it with `npx -y onlinecybertools-mcp-server`
— no clone, no global install. The config snippets below work as-is and
expose the **full tool catalogue** by default.
Prefer a guided setup? Generate a ready-made Claude Code plugin or Codex
config block from the website's interactive builder:
**<https://onlinecybertools.com/integrations/mcp-plugin-builder>**
The builder lets you pick a subset of tools and emits the matching
`OCTOOLS_TOOLS` filter for you (see [Configuration](#configuration)).
## Configuration
Configure via environment variables. All are optional.
| Variable | Default | Purpose |
|---------------------------------|-----------------------------------------|---------|
| `OCTOOLS_BASE_URL` | `https://onlinecybertools.com` | Site to proxy requests to. |
| `OCTOOLS_TOOLS` | _(unset → all tools)_ | Comma-separated menu IDs (`base64_encode,sha256,hash`) to restrict the exposed surface. **Leave unset to expose every tool** — the examples below omit it on purpose. |
| `OCTOOLS_STREAM_BYTE_CAP` | `262144` (256 KiB) | Max bytes accumulated from a streamed (`x-mcp-compatible: stream-buffered`) endpoint. |
| `OCTOOLS_STREAM_TIME_CAP_MS` | `30000` (30 s) | Max wall-clock time spent buffering a streamed endpoint. |
When `OCTOOLS_TOOLS` is set, the server appends `?tools=...` to the spec
fetch so the site returns a pre-filtered spec; the client also enforces the
filter as defense-in-depth.
## Running
### Inspector (manual smoke test)
```bash
npx @modelcontextprotocol/inspector npx -y onlinecybertools-mcp-server
```
Open the inspector URL, click **List Tools** — you should see `search`,
`describe_tool`, `report_bug`, plus one entry per compatible Symfony API
operation. With no `OCTOOLS_TOOLS` set, the full catalogue is listed.
To hack on the server locally instead, clone and run from source:
```bash
git clone https://github.com/Jambozx/onlinecybertools-mcp-server.git
cd onlinecybertools-mcp-server
npm install
npx @modelcontextprotocol/inspector node index.mjs
```
### Claude Code
Add to `~/.claude.json` (or your project's `.mcp.json`):
```json
{
"mcpServers": {
"octools": {
"command": "npx",
"args": ["-y", "onlinecybertools-mcp-server"]
}
}
}
```
This exposes every tool. To restrict the surface, add an `env` block with
`OCTOOLS_TOOLS`:
```json
{
"mcpServers": {
"octools": {
"command": "npx",
"args": ["-y", "onlinecybertools-mcp-server"],
"env": {
"OCTOOLS_TOOLS": "base64_encode,sha256,hash"
}
}
}
}
```
### Codex
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.octools]
command = "npx"
args = ["-y", "onlinecybertools-mcp-server"]
```
To restrict the surface, add an `env` line with `OCTOOLS_TOOLS`:
```toml
[mcp_servers.octools]
command = "npx"
args = ["-y", "onlinecybertools-mcp-server"]
env = { OCTOOLS_TOOLS = "base64_encode,sha256,hash" }
```
### Cursor / Continue / generic MCP client
Most clients accept the same `command`/`args`/`env` shape. Point them at
this package via `npx -y onlinecybertools-mcp-server`.
## Streaming endpoints
Endpoints tagged `x-mcp-compatible: stream-buffered` in the spec (currently
traceroute and proxy-test streams) are read to completion and returned as a
single JSON envelope of accumulated SSE events. GET stream endpoints send tool
arguments as query parameters; POST streams send JSON bodies. Hard caps:
- 256 KiB of buffered output (`OCTOOLS_STREAM_BYTE_CAP`)
- 30 s of wall-clock time (`OCTOOLS_STREAM_TIME_CAP_MS`)
Whichever cap fires first, the response envelope contains
`{ "truncated": true }` so the agent knows the output is partial.
Endpoints tagged `x-mcp-compatible: none` (multipart file uploads, etc.) are
**skipped at registration** — they will not appear in `tools/list`.
## Limitations
- Spec is fetched **once at startup**. If the site adds new endpoints, restart
the server.
- stdio transport only; no HTTP server (avoids needing auth in front of a
privileged endpoint).
- Published to npm as `onlinecybertools-mcp-server`
(`npx -y onlinecybertools-mcp-server`). Installing straight from GitHub
(`npx -y github:Jambozx/onlinecybertools-mcp-server`) still works for the
bleeding edge.
## License
MIT.
