Building GhostMCP: A Cybersecurity MCP Server for Agents

2/7/2026

When I started GhostMCP, the goal was simple: build a real MCP server for security workflows that agents could use reliably in production, not just a demo that runs on localhost once.

This post walks through what I built, what broke, and what made it production-ready.

Why GhostMCP Exists

Most security tooling is still designed for humans at a terminal. Agent systems need something different:

  • A stable MCP contract with typed tool schemas
  • Consistent runtime behavior under automation
  • Guardrails for authorized testing workflows
  • Operational controls (auth, observability, shutdown, CI/CD)

GhostMCP bridges that gap by exposing security tooling as MCP tools with policy and lifecycle controls.

Core Design

GhostMCP has two categories of tools:

  • Core tools implemented in Python (DNS, WHOIS, HTTP probe, TLS inspection, IOC extraction, metrics, health)
  • Binary-backed tools discovered from installed Kali-style binaries and exposed only when present

At startup, GhostMCP scans for common binaries and enables only what exists on PATH. This avoids advertising tools that cannot execute.

Key Production Decisions

1. Dynamic Tool Registration by Installed Binaries

I wanted one system, not fragmented static vs dynamic behavior.
The server now builds a unified registry and prints startup availability like:

  • Tools enabled: X/Y
  • Binary tools enabled: A/B
  • Enabled binaries: ...

That gives immediate operator clarity and prevents broken calls from missing binaries.

2. Correct MCP Tool Schemas

One of the most important fixes was schema correctness.
Early on, tool calls failed because the advertised argument contract didn’t match the real function signature.

I fixed this by preserving function signatures and annotations so MCP clients validate and call tools correctly.

3. Reliable Shutdown and Process Cleanup

In long-running agent setups, shutdown behavior matters.
GhostMCP now handles SIGINT/SIGTERM, tracks active subprocesses, and terminates child processes during shutdown. This fixed E2E timeout behavior where tests could hang waiting for process exit.

4. Security and Policy Controls

GhostMCP enforces practical controls for authorized operations:

  • Engagement context fields (engagement_id, engagement_mode)
  • Tool-level authorization ceilings
  • Rate limiting and concurrency controls
  • Raw tool argument validation and runtime/output limits
  • Optional token auth and mTLS in remote transport mode
  • Blocking insecure remote unauthenticated mode unless explicitly overridden

5. Observability First

I added:

  • Structured JSON logs
  • Audit events with hash chaining
  • Metrics (calls, failures, timeouts, denied requests, durations)
  • Runtime and health probe tools
  • Optional SIEM-friendly JSONL audit sink

This makes incident response and troubleshooting much easier.

CI/CD and Release Hardening

To make the project maintainable:

  • GitHub Actions CI: Ruff, Mypy, Bandit, unit/integration tests, build checks
  • CodeQL scanning
  • Release workflow for tagged builds and artifact checks
  • Dependabot support
  • Packaging fixes for editable installs and top-level package discovery

A lot of “production-ready” work was actually in this layer, not tool logic.

Biggest Lessons

  1. Correct interface contracts are everything for MCP interoperability.
  2. Runtime behavior beats feature count. Startup introspection and clean shutdown saved more time than adding one more tool.
  3. Security controls must be explicit and testable, not implied.
  4. CI failures often come from workflow logic, not just code.

What’s Next

GhostMCP is now in a strong operational state, but the roadmap includes:

  • Deeper E2E protocol tests with real clients
  • More granular per-tool policy profiles
  • Expanded deployment blueprints for container/systemd environments
  • Optional stronger sandboxing for external binaries

Closing

GhostMCP started as “wrap some security tools for agents.”
It became a full engineering exercise in contracts, safety, lifecycle, and reliability.

If you’re building MCP servers for high-impact domains, this is the main takeaway:
the hard part is not exposing tools — it’s making them dependable under real automation.

Comments