MCP — Model Context Protocol

All Stygian MCP servers expose capabilities over the Model Context Protocol (MCP). The standalone stygian-graph, stygian-browser, and stygian-proxy servers speak MCP 2025-11-25; the stygian-mcp aggregator additionally supports protocol negotiation for 2025-11-25, 2025-06-18, and 2024-11-05.

This gives LLM agents, IDE plug-ins, and automation pipelines a stable JSON-RPC surface for web scraping, browser control, and proxy pool management without writing Rust code.

Deployment modes

Mode	Crate / deployment	When to use
Graph MCP	`stygian-graph` (embed `McpGraphServer` in your binary)	Scraping pipelines and DAG execution only
Browser MCP	`stygian-browser` (embed `McpBrowserServer` in your binary)	Browser automation only
Proxy MCP	`stygian-proxy` (embed `McpProxyServer` in your binary)	Proxy pool management only
Aggregator	`stygian-mcp` (binary)	All capabilities in one server — recommended

For most LLM agent integrations, run the aggregator — it merges all three tool surfaces into a single stdin/stdout MCP server and adds two cross-crate tools (scrape_proxied, browser_proxied) that orchestrate proxies and scraping/browser together.

When stygian-graph is built with its charon feature, the graph surface also exposes feature-gated graph_charon_* diagnostics and runtime-planning tools.

Quick start — aggregator

# Build the unified server
cargo build --release -p stygian-mcp

# Run it (MCP clients communicate over stdin/stdout)
./target/release/stygian-mcp

VS Code configuration

Add to .vscode/mcp.json (or your client's MCP config file):

{
  "servers": {
    "stygian": {
      "type": "stdio",
      "command": "/path/to/target/release/stygian-mcp",
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Protocol

All servers implement JSON-RPC 2.0 over stdin/stdout. Newline-delimited requests in, newline-delimited responses out.

Notifications (messages without an id) do not produce responses.

The implementation follows MCP 2025-11-25 message shapes for tool schemas, tool content blocks, and resource payloads. For protocol details, see the official spec: https://modelcontextprotocol.io/specification/2025-11-25.

Method	Description
`initialize`	Handshake — returns `protocolVersion`, capabilities, and `serverInfo`
`tools/list`	Returns the complete list of available tools with JSON Schema for each
`tools/call`	Invoke a tool by name with `arguments`
`resources/list`	List active sessions / pool state as MCP resources
`resources/read`	Read a resource by URI

Tool namespaces (aggregator)

When using the aggregator, all tools are namespaced:

Prefix	Sub-server
`graph_`	stygian-graph — e.g. `graph_scrape`, `graph_pipeline_run`, `graph_charon_analyze_and_plan`
`browser_`	stygian-browser — e.g. `browser_acquire`, `browser_navigate`
`proxy_`	stygian-proxy — e.g. `proxy_add`, `proxy_acquire`
(none)	Aggregator cross-crate — `scrape_proxied`, `browser_proxied`

When using a per-crate MCP server standalone, graph tools are un-prefixed (e.g. scrape instead of graph_scrape).

Cross-crate tools

These tools are only available in the aggregator and orchestrate multiple sub-systems automatically.

`scrape_proxied`

Fetch a URL through a proxy automatically selected from the pool.

Acquires an available proxy via proxy_acquire.
Performs an HTTP scrape through that proxy.
Releases the proxy, marking it as healthy or failed for circuit-breaker accounting.

Parameter	Type	Required	Description
`url`	string	✓	Target URL
`timeout_secs`	integer		Request timeout (default: 30)

Returns the scraped content in MCP content format.

`browser_proxied`

Navigate in a headless browser routed through a proxy from the pool.

Acquires a proxy via proxy_acquire.
Acquires a browser session configured to use that proxy.
Navigates to the URL and captures navigation metadata + full HTML.
Releases the browser session and proxy.

Parameter	Type	Required	Description
`url`	string	✓	Target URL

Returns { "navigation": { ... }, "html": "<html>..." } as MCP text content.

Logging

The servers write diagnostic output to stderr only; stdout is reserved for the JSON-RPC channel. Control verbosity via the RUST_LOG environment variable:

RUST_LOG=stygian_mcp=debug,stygian_graph=info ./stygian-mcp

Production Security Baseline

Production MCP deployments should enforce controls at the gateway/server boundary, not only inside individual agents.

1) PII redaction before model context

Redact or pseudonymize sensitive fields on tool outputs before they enter model context.
Apply centrally so every agent/tool path gets the same treatment.
Keep an auditable trail of redaction events for compliance reviews.

2) Input guardrails (prompt-injection resistance)

Scan untrusted content (user input, retrieved pages, tool outputs) for instruction-like payloads.
Flag jailbreak-style text and imperative operation prompts in data channels.
Use stricter checks for low-trust sources (scraped/public content).

3) Output guardrails (egress control)

Validate tool call parameters before write/send/delete operations.
Enforce output schema and content policy checks.
Block PII leakage in agent-visible responses and outbound tool payloads.

4) Data exfiltration prevention (session-level)

Monitor tool-call sequences, not only single calls.
Alert on unusual read volume and cross-tool data movement (read -> send/write).
Restrict communication destinations to approved allow-lists.

5) Access and incident readiness

Apply least-privilege RBAC per tool.
Log each tool call with agent identity, request, response, and guardrail outcome.
Maintain a runbook to quickly suspend agent/tool access without full downtime.

Operational checklist:

PII redaction active for sensitive tool outputs.
Input guardrails enabled and tuned for source trust levels.
Output guardrails enabled for all write-capable tools.
Destination allow-lists enforced for outbound channels.
Session traceability enabled for exfiltration/anomaly investigations.