MCP discovery and runtime control

Plan requirement: Enterprise.

The MCP agent scans supported local configuration locations for known MCP clients such as Cursor, Windsurf, VS Code, Claude Desktop, Claude Code, and Codex. It reports a sanitized inventory containing names and command or URL metadata. Its optional runtime proxy can also launch an explicitly configured stdio MCP server and apply allow, deny, approval-required, or redaction decisions to tool calls.

Deploy the MCP agent

1. Provision an MCP agent key under Sensors & keys in an Enterprise organization. A browser, desktop, or gateway key is rejected.
2. Install the MCP agent on a test endpoint.
3. Install only ORTHALON_SENSOR_KEY through the endpoint secret profile. The signed agent already contains the Orthalon service address.
4. Run pnpm scan:mcp first and inspect the sanitized output locally. This command sends nothing and exits.
5. Confirm that environment values, tokens, headers, and command arguments that contain secrets are absent.
6. Run the connected reporter (pnpm dev:mcp during development, or the built agent with --watch=60 on an endpoint) and verify a Reported ... result.
7. Deploy with launchd on macOS, Task Scheduler or a service on Windows, or systemd on Linux.

Protect a stdio MCP server

1. Put the server on an administrator allowlist; never accept an arbitrary command supplied by an untrusted client.
2. Start the server through the MCP runtime proxy documented in the deployment package rather than connecting the client directly to the server.
3. Enumerate tools and confirm the inventory keeps only name, optional title, and safe read-only/destructive/idempotent/open-world hints. Descriptions, input schemas, arguments, environment values, and headers are discarded.
4. Apply a deny rule to a harmless test tool and confirm the call receives a JSON-RPC policy error.
5. Apply an approval-required rule and confirm the stdio call waits for the central approval decision without sending tool arguments. Approve it and confirm the exact fingerprint, server/tool restriction, expiry, and use count are consumed before the call reaches the server.
6. Verify audit records go to the protected local diagnostic stream and that raw arguments, environment values, and tool output are absent.

The runtime defaults to deny when no policy file or JSON is configured. Messages are bounded to 8 MB, while tool arguments and protected results must fit the 1 MB complete-inspection budget. Oversized or excessively nested calls fail closed; they are never partly redacted and forwarded. Duplicate or excessive in-flight JSON-RPC request IDs are rejected. If the central approval service is unavailable or the approval expires, that tool call fails closed without terminating the wrapped MCP server.

For fleet policy updates, deploy the stdio rules through ORTHALON_MCP_POLICY_FILE or the proxy's --policy option. Replacing that managed JSON file reloads valid rules without restarting the wrapped server. An invalid, oversized, or partially written replacement is rejected and the last valid policy remains active. ORTHALON_MCP_POLICY_JSON is read from the process environment at startup and therefore requires a process restart when changed.

This stdio tool policy is separate from the organization content-policy bundle. The MCP agent automatically reports inventory, but HTTP and SSE connections remain inventory-only and do not receive browser, desktop, or gateway policy rules.

The ingest service rejects MCP reports from a non-Enterprise organization.

Validate changes

Add a harmless local test MCP configuration, run the agent again, and confirm the inventory changes. Remove the configuration and confirm the next report marks that endpoint observation inactive. Revoke the sensor key and verify future reports fail.

Supported automatic locations include the user configurations for Cursor, Windsurf, VS Code, Claude Desktop, Claude Code (~/.claude.json), and Codex (~/.codex/config.toml). Claude Code project locations are represented by an irreversible local path hash; the path itself is not reported. VS Code workspace .vscode/mcp.json and project-scoped Codex .codex/config.toml files are not crawled automatically because a fleet agent must not traverse every employee project directory. Put fleet-managed entries in the supported user configuration or wrap the approved stdio server to report its runtime inventory.

Do not use real tokens in test configurations or attach raw endpoint config files to support tickets. Store the MCP-scoped key in Keychain, Credential Manager/DPAPI, or a protected systemd environment file and rotate it before expiry. ORTHALON_INGEST_URL is an operator-only local/staging override, not an employee enrollment question.

The runtime proxy currently supports stdio transport. HTTP and SSE MCP servers are inventory-only; transparent interception of an existing remote connection is not claimed as supported.