Secure Usage MCP Server

This Model Context Protocol (MCP) server enforces secure-by-design guardrails for AI-assisted development.

Features

• Secure coding guidance (secure-code-review) – Produces a NIST SSDF and OWASP-aligned remediation plan, stack-specific hardening tips, and verification checklist. Optional code snippets are scanned for common anti-patterns (hardcoded secrets, eval, weak crypto, etc.).
• High-risk tool mediation (tool-risk-gatekeeper) – Evaluates planned tool executions for destructive operations (filesystem, infrastructure, database). Flags commands that require human approval and emits a ready-to-display confirmation prompt.
  • Also ships a CLI gate binary secure-usage-gate that classifies shell commands before running them. It can optionally consult an LLM for hybrid decisions.
• Agent configuration hardening (agent-configuration-hardener) – Builds an endpoint hardening blueprint for IDE, CLI, and vibe coding agents. Covers sandboxing, remote indexing controls, plugin/MCP inventories, reasoning guardrails, and monitoring playbooks.
• Reusable guardrail prompt – Exposes the secure-coding-governor prompt that IDEs/agents can apply as a baseline secure coding instruction set.

Getting Started

Runtime requirements

• Node.js 18.17.0 or newer.

Run with npx

Install and launch the compiled server directly from npm without cloning the repository:

npx -y secure-usage-mcp@latest

This resolves the published package, runs the compiled binary declared in the package manifest, and exposes the MCP server over STDIO. The shebang header ensures npx can execute it on all major platforms.

Run from source

npm install
npm run build
npm start

The server communicates over STDIO. Integrate it with an MCP-compatible client (e.g., Claude Desktop, Cursor, or custom tooling) by referencing the compiled binary secure-usage-mcp.

Configuration

• SECURE_USAGE_LOG_LEVEL – Optional log level override (debug, info, warn, or error). Logs are emitted to stderr so the MCP protocol payloads on stdout remain untouched..

Testing the MCP Server

1. Build the server output:

   npm run build

2. Run the automated smoke test, which spawns the compiled server via the MCP SDK client and exercises both tools:

   node scripts/smokeTest.mjs

   The script prints the server instructions, a preview of the secure-coding-governor prompt, and structured output from the two tools. It also verifies that high-risk tooling requires an explicit Yes/No confirmation.

3. For a minimal verification that focuses on risk mediation, execute the included test-client.js script:

   node test-client.js

   This script connects to the built server, prints the instructions, and runs a sample tool-risk-gatekeeper request to confirm high-risk detection.

4. For interactive debugging, you can also run the server manually and inspect it with the open-source MCP Inspector:

   npm start # in one terminal

   Follow the Inspector README to point it at node dist/index.js via stdio and explore prompts/tools in a GUI.

IDE Integration

Cursor

1. Open Settings → Experimental → MCP Servers (or edit ~/.cursor/config.json).

2. Register the server with the published npm package so Cursor can resolve it via npx:

   {
     "mcpServers": {
       "secure-usage": {
         "command": "npx",
         "args": ["-y", "secure-usage-mcp@latest"],
         "env": {}
       }
     }
   }

3. Restart Cursor. When a high-risk tool call is attempted, the chat panel will show a Yes/No confirmation. Answer No (or anything other than Yes) to halt execution.

Claude Code (Claude Desktop)

Claude Code supports MCP servers over STDIO via a JSON config. You can either reference the built script directly or use npx to always fetch the latest published version.

1. Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Recommended: configure via npx so Claude resolves the published package automatically:

{
  "mcpServers": {
    "secure-usage": {
      "command": "npx",
      "args": ["-y", "secure-usage-mcp@latest"],
      "env": {}
    }
  }
}

Alternatively, point directly at a local build (useful for development):

{
  "mcpServers": {
    "secure-usage": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/secure-usage-mcp/dist/index.js"],
      "env": {}
    }
  }
}

On Windows, adjust paths accordingly, for example:

{
  "mcpServers": {
    "secure-usage": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": ["C:/Users/<you>/projects/secure-usage-mcp/dist/index.js"],
      "env": {}
    }
  }
}

3. Save and relaunch Claude Code. Open the MCP panel to confirm the server is connected. The guardrail prompt secure-coding-governor becomes available, and destructive tools will require a Yes/No confirmation.

Verify

• Ask Claude to run a risky command (e.g., mention rm -rf /tmp/demo) after connecting. You should see a risk assessment and a Yes/No prompt from tool-risk-gatekeeper.
• Call the secure guidance tool by asking Claude to use secure-code-review with your request and a short code snippet.

Troubleshooting

• If the server does not appear: ensure Node ≥ 18.17.0 is installed and on PATH inside Claude.
• If you see permission errors with npx: pre-install globally with npm i -g secure-usage-mcp and set command to secure-usage-mcp (no args).
• If stdout looks noisy: this server logs to stderr by default. Ensure your config does not redirect stderr to stdout.
• If high-risk prompts aren’t shown: your client must surface the userPrompt and block execution until the operator answers "Yes". Treat any other response as "No".

The guardrail policy requires explicit human approval. If an IDE cannot surface a Yes/No prompt, treat that as a No and halt.

Shell Command Gate (Optional)

Install exposes secure-usage-gate, which classifies and optionally blocks commands:

secure-usage-gate -- git push origin main
secure-usage-gate -- rm -rf build/

Environment variables:

• SECURE_USAGE_LOG_LEVEL – debug|info|warn|error (stderr).
• SECURE_USAGE_EVAL_MODE – regex|llm|hybrid (default regex).
• SECURE_USAGE_LLM_PROVIDER – openai (default).
• SECURE_USAGE_LLM_MODEL – OpenAI model (default gpt-4o-mini).
• OPENAI_API_KEY – required for llm/hybrid modes.
• SECURE_USAGE_GATE_EXECUTE – set 0 to classify only (no exec).

Git pre-push hook example

Create .git/hooks/pre-push and make it executable:

#!/bin/sh
cmd="git push $@"
secure-usage-gate -- "$cmd"

To require force-push approvals only:

#!/bin/sh
case "$*" in
  *"--force"*|*"-f"*) secure-usage-gate -- "git push $@" ;;
  *) exit 0 ;;
esac

Workflow Recommendations

1. Wrap AI code generation by calling secure-code-review with the request context and candidate code. Adopt the returned mitigations before accepting any changes.
2. Guard destructive tooling by routing every mutation command through tool-risk-gatekeeper. If requiresApproval is true, surface the provided userPrompt to the operator and block execution until they explicitly approve.
3. Lock down agent configurations using agent-configuration-hardener before enabling new plugins, MCP servers, or vibe coding agents. Apply the per-agent runtime controls, sandbox requirements, and monitoring hooks it prescribes.
4. Apply the secure prompt secure-coding-governor as a system/assistant message to keep large language models aligned with NIST and OWASP requirements.

Tool Reference

• secure-code-review – Request/response schema, response structure, and usage tips for the secure guidance generator.
• tool-risk-gatekeeper – Input parameters, output contract, and operator workflow for high-risk tooling mediation.
• agent-configuration-hardener – Inventory format, policy coverage, and sample outputs for IDE/CLI/vibe agent hardening.

Development

• npm run dev – Start the TypeScript server with hot reload using ts-node.
• npm run build – Compile TypeScript to JavaScript (output in dist/).
• npm start – Run the compiled server.

License

This project is licensed under the MIT License. See LICENSE.