MCP Tool Plugins

The MCP Tool Plugins section in Global Settings lets you plug any Model-Context-Protocol (MCP) server into RedAmon's agent — Shodan, GitHub, Burp, your own internal tools — without editing code, rebuilding containers, or running database migrations. Each MCP server you add becomes a tool plugin that extends the agent's tool arsenal. Add one in two clicks via Quick Add presets or a manual form. The tools the plugin exposes are auto-injected into the agent's system prompt and become available in every project's Tool Matrix.

Naming: a tool plugin is, technically, a Model-Context-Protocol server that the agent connects to. The product term MCP Tool Plugin disambiguates these from the 5 baseline system MCP servers that ship inside the kali-sandbox container (network_recon, nmap, nuclei, metasploit, playwright) and back the agent's built-in pentest toolset.

Why this matters: RedAmon's agent ships with 25 baseline tools (the 5 system MCP servers wrapping Kali Linux + 7 built-ins). Beyond those, the offensive-security ecosystem has hundreds of MCP servers you can plug in — covering everything from CVE intel to cloud audit to reverse engineering. This page is the operator manual for adding them.

Looking for the technical deep dive? See docs/readmes/README.MCP.md for the protocol-level architecture, the Python schema, the prompt-rendering pipeline, and how runtime tool dispatch works.

Concepts in 60 seconds

Where to find it

Open Global Settings (gear icon, top-right of the navbar) → MCP Tool Plugins tab.

You'll see three areas:

1. Header — title + the red Add MCP button (top right).
2. Quick add — 33 prefilled preset cards in a scrollable grid.
3. Saved plugins table — empty until you save your first plugin.

Quick add — the easy path

The 33 preset cards cover the most useful MCP servers (i.e., MCP Tool Plugins) for pentest work, all verified live with correct install commands.

Preset card anatomy

Each card shows:

• Label — short name (e.g. Shodan)
• Category tag — one of OSINT, Research, Web/HTTP, Security, Utility (top-right of the card)
• Blurb — one-line summary
• Transport tag — stdio or streamable_http
• Auth tag — appears in orange if the preset requires an API key
• Already added tag — appears in green if you've already saved this preset

Hover any card to see the full "why this matters for RedAmon" tooltip — the strategic pentest use case.

Click → form opens prefilled

Click a card and the manual form opens with everything filled in except the secret (token / API key). You paste your key, click Test, and Save.

The 33 presets at a glance

Research / Reasoning (4)

OSINT / Search (7)

Security / Threat Intel (9)

Cloud (1)

Web / Browser (2)

Utility / Reasoning / Reporting (7)

Reverse Engineering (3)

Note: 4 presets need extra setup (Trivy, Prowler, CVE Intel extended, GhidraMCP) — flagged with a setup hint in their tooltip. Form fields are still pre-populated with the exact command/args that work after the documented setup runs.

Manual Add MCP — full control

Click the red Add MCP button at the top right when you want to configure a server that isn't in the preset list (your internal MCP, a community fork, a custom build).

Form fields

Transport-specific fields

When you pick streamable_http or sse:

When you pick stdio:

Auth: bearer token field (HTTP transports only)

• Paste the literal token (e.g. ghp_abcd1234...) into the password input.
• The token is stored as-is in the DB alongside your other API keys (UserSettings.tavilyApiKey, etc.) — same pattern.
• After Save, the form re-loads it as ••••••••<last4> (masked). To rotate, type the new value over the mask.

Security note: never paste tokens into chat or commit them. They live only in your user row in Postgres — same trust boundary as Tavily/Shodan/SerpAPI keys you already store there.

Discover and add new tools — the Test button

After filling the server connection details (transport + url/command + auth if needed), click the orange Discover and add new tools button at the top right of the form.

What it does:

1. Opens a one-off MCP session against your draft (does NOT touch any saved servers or running scans).
2. Calls the protocol-level list_tools() against the upstream MCP.
3. Returns within 30 seconds with the full list of tools the server exposes — name, description, and JSON input schema for each.
4. Renders a scrollable table below.

What the table shows

+ Add (per-tool import) vs + Add all

• + Add on a single row — imports just that tool into your form's Tools list.
• + Add all at the top — imports every tool that isn't already added or reserved. One click.

Both paths populate all four required strategic fields automatically:

You can hit Save immediately. Or refine when_to_use to make it more strategic (this is the field the LLM weights heaviest when choosing which tool to call).

Test handles auth gracefully: the masked-token placeholder (••••••••XXXX) is automatically swapped for the real saved token before the test request leaves the browser, so clicking Test on an already-saved server works the same as a freshly-pasted token.

The Tools list — what the LLM sees

Each tool entry has 5 fields, all of which get injected into the agent's system prompt. Hover the → injected in LLM prompt badge on each label for the exact prompt section it lands in.

→ injected in LLM prompt badge

Every LLM-bound field has a small blue badge next to its label. Hover for a tooltip that explains exactly which section of the system prompt the field lands in.

Per-tool default_phases override

Below description, each tool has its own 3 phase checkboxes. By default a tool inherits the server's default_phases. Untick any to remove it from that phase only — useful when one tool of a multi-tool server is exploit-only while the rest are recon.

Add Tool Manually

If the server's list_tools() doesn't expose everything (rare) or you want to declare a tool with custom strategic guidance, click + Add Tool Manually in the right side of the Tools section header. A blank tool block appears for you to fill manually.

Saving and what happens next

Click the red Save button at the top of the form. The webapp:

1. Re-validates the entire server with zod — strict; rejects half-filled tool specs with field-level errors.
2. Performs cross-server uniqueness checks (server id, tool names) against your existing saved servers.
3. Persists the row into UserSettings.mcpServers (a JSON column).
4. Fires POST /mcp/reload against the agent (fire-and-forget) so the running agent re-registers the new tools.

You return to the list view. Your new server appears in the saved-servers table with: name, transport pill, tool count, an Enabled toggle, and edit / delete buttons.

What the LLM sees on the next chat message

Within ~1 second of Save, the next chat / scan message you send uses an updated system prompt that includes:

• Each declared tool name in the tool_name enum
• Each tool's purpose + when_to_use in the availability table
• Each tool's args_format in the args reference section
• Each tool's description in the detailed-guidance block (every phase where the tool is allowed)

Verify any time:

curl -s http://localhost:8090/mcp/manifest | python3 -m json.tool

The servers[].tools[] array shows what the agent currently has loaded.

Editing and deleting

Edit

Click the pencil icon in the Actions column. Form opens with all fields populated (auth token masked). Change anything except id. The masked token is preserved if you don't touch it; a fresh value is taken if you type over the mask.

Toggle enabled

The switch in the Enabled column flips immediately — no form needed. A disabled server's tools are removed from the registry on the next reload.

Delete

Click the trash icon → confirmation modal appears (themed, not the browser's gray dialog). Confirm to remove. The agent reloads and the tools disappear from every project's Tool Matrix on next page load.

How it shows up in your projects

Project Tool Matrix

Every project's settings page has a Tool Matrix tab where you toggle each tool on/off per phase. After you add an MCP server here, its tools auto-appear in that matrix — no per-project setup needed.

The matrix has two regions:

• Built-in tools — the 25 hardcoded tools (query_graph, web_search, the 18 system MCP-backed tools, etc.) listed flat.
• MCP Tools — a separate section with one collapsible <details> block per user MCP server you've saved. Tools inherit their default phases until you toggle them.

Agent chat — wrench icon tooltip

The wrench icon next to the phase badge in the agent chat shows a live list of tools available in the current phase.

The tooltip is interactive — hover the wrench, then move your mouse onto the tooltip body to scroll through the full list. Two sections:

• Phase Tools — built-ins + tools you've explicitly toggled in the project's Tool Matrix.
• MCP Tools — user MCP tools whose default phases include the current phase.

The 300-px scroll cap keeps long lists (e.g. 41 GitHub tools) compact.

Recommended testing order

If this is your first time setting up an MCP, work through the presets in this order to build confidence:

1. DeepWiki — no auth, just paste and click Test. Confirms the entire pipeline works end-to-end. ~10 seconds.
2. Time — stdio, no auth. Confirms the agent's uvx runtime works for Python stdio MCPs.
3. GitHub (with a real PAT) — exercises the bearer-token + masked-restore + 41-tool discovery path. Use + add all to see the auto-fill in action across many tools.
4. A Threat Intel preset (Shodan, VirusTotal, or HIBP) — confirms env-var auth and that the discovered args_format carries enums + min/max + descriptions through to the prompt.
5. A complex preset (mitmproxy or Browserbase) — confirms multi-env-var stdio configs.

For each, watch agentic/logs/agent.log for:

INFO orchestrator | MCP manifest reload: N user server(s), M declared tool(s), K live tool(s) registered.

If M > 0 but K == M plus your built-in count, you're good. If K < M, the upstream server didn't expose all tools you declared — check the Test button's discovered list against your Tools list to see the gap.

Example: white-box pentest using the GitHub preset

Once you've added the GitHub preset and clicked + add all in the Test panel to import its ~40 tools, you can drive a full white-box / gray-box pentest from the agent chat. The agent has both the source-side tools (from GitHub MCP) and the live-target tools (execute_curl, execute_playwright, execute_nuclei, metasploit_console, ...) in the same prompt — so it iterates freely between code analysis and live verification.

Two prerequisites:

1. The GitHub PAT you saved must have read access to the target repo.
2. Turn off the Agent Guardrail toggle in the project's Agent Behaviour settings (this sets AGENT_GUARDRAIL_ENABLED = false). Otherwise the agent may refuse to use the GitHub tools: the scope reminder injected into its prompt tells it to operate only against the project's configured target_domain / target_ips, and github.com is outside that scope. There is no per-repo allowlist to add instead, the scope is keyed on the live target, so the guardrail toggle is the switch to use.

Then drop this prompt into the agent chat — replace <ORG>/<REPO> with the source repo and <TARGET_URL> with the live-target URL already configured in the project:

White-box pentest on the live target.

Source: github.com/<ORG>/<REPO>
Target: <TARGET_URL>

Iterate freely between source analysis and live testing — don't linearize.
Read code with the GitHub tools to form hypotheses, then verify each
hypothesis against the live target with the existing pentest tools.
Whatever you find on the live side, go back to the code to understand
why and find adjacent variants.

Persist findings in the graph as you go. Stop when coverage plateaus.

What you'll see in the timeline:

• search_code calls with attacker-pattern queries (SELECT.*FROM.*\$, eval(, dangerouslySetInnerHTML, hardcoded secret regex, etc.) — fast, surgical, low token cost.
• get_file_contents calls when a hit needs context.
• execute_curl / execute_playwright / execute_nuclei calls verifying each candidate against the live target.
• query_graph updates as confirmed findings become Vulnerability nodes.

The same prompt-shape works for any source-aware MCP — swap in GitLab MCP or your internal code-search MCP the same way.

Note: this is freeform white-box mode driven by your prompt. A dedicated white_box_audit skill (under Agent Skills) with a curated 5-phase methodology is a natural follow-up if you find yourself running this regularly.

Troubleshooting

Validation rules cheat sheet

zod (form / API route) and pydantic (agent) enforce identical rules — these will reject saves:

• id must match ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$ and not collide with the 5 system server IDs.
• Tool names must not collide with built-in tool names (query_graph, execute_nmap, kali_shell, etc.) or with another tool name across your saved servers.
• HTTP transports require a non-empty url. stdio requires a non-empty command.
• All four tool fields (name, purpose, when_to_use, args_format, description) must be non-empty.
• auth (when present) must specify either token (literal) or token_env_var (env var name) — at least one.

Cross-server uniqueness is enforced after individual schemas pass.

Storage & security model

• Where it lives: UserSettings.mcpServers JSONB column in Postgres. Same trust boundary as your other API keys (tavilyApiKey, shodanApiKey).
• Token at rest: stored as plaintext in the DB — same trust boundary as your other API keys (Tavily / Shodan / SerpAPI). Headers and stdio env values are also stored as literal strings; no ${VAR} substitution is performed.
• Token in transit (within the stack): webapp → agent over the internal Docker network only. Never serialized into log lines.
• Token at the boundary: the agent forwards it as Authorization: Bearer <token> verbatim when calling the upstream MCP.
• Display: API responses always mask the token (••••••••<last4>). The mask never reaches the upstream MCP — the proxy substitutes it back from DB before forwarding.
• Defense in depth: the agent rejects bearer tokens containing non-ASCII chars (catches the masked placeholder ever leaking through, returns a clean error instead of crashing httpx).

See also

• AI Agent Guide — chat interface, agent phases, where MCP tools surface in the timeline.
• Global Settings — full Global Settings reference. The MCP Tool Plugins tab is one of seven; LLM Providers and API Keys live next door.
• Project Settings Reference — every project parameter, including the Tool Matrix agentToolPhaseMap JSON column that user MCP tools surface in.
• Agent Skills — built-in workflows (CVE exploit, brute force, phishing) that use built-in tools. MCP tools complement skills — the LLM sees both in the same prompt.
• docs/readmes/README.MCP.md — protocol-level architecture, schema, and runtime tool dispatch internals.

← Back to Home | → Project Settings Reference