# MCP — Model Context Protocol

All Stygian MCP servers expose capabilities over the
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/). 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 |
| **Plugin MCP** | `stygian-plugin` (embed `McpPluginServer` in your binary) | Recorded-template extraction fallback 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

```sh
# 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):

```json
{
  "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](./graph-tools.md) — e.g. `graph_scrape`, `graph_pipeline_run`, `graph_charon_analyze_and_plan` |
| `browser_` | [stygian-browser](./browser-tools.md) — e.g. `browser_acquire`, `browser_navigate` |
| `proxy_` | [stygian-proxy](./proxy-tools.md) — e.g. `proxy_add`, `proxy_acquire` |
| `plugin_` | [stygian-plugin](./plugin-tools.md) — e.g. `plugin_create_template`, `plugin_apply_template` |
| *(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.

1. Acquires an available proxy via `proxy_acquire`.
2. Performs an HTTP scrape through that proxy.
3. 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.

1. Acquires a proxy via `proxy_acquire`.
2. Acquires a browser session configured to use that proxy.
3. Navigates to the URL and captures navigation metadata + full HTML.
4. 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:

```sh
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.
