MCP Inspector README

@gridinsoft/mcp-inspector

A Model Context Protocol server for domain reputation and URL analysis, powered by GridinSoft Inspector.

Requirements

Node.js 22 or newer, with npm/npx available to your MCP host.
A GridinSoft Inspector API key from your profile.

The npm package runs locally over stdio and calls the Inspector REST API over HTTPS. https://inspector.gridinsoft.com/mcp is the documentation page; /mcp/v1 is the REST bridge used by this package. Neither URL is a native remote MCP Streamable HTTP or SSE endpoint.

Connect an MCP client

Add this entry to your client's MCP server configuration:

config.json

{
  "mcpServers": {
    "gridinsoft": {
      "command": "npx",
      "args": ["-y", "@gridinsoft/mcp-inspector"],
      "env": {
        "GRIDINSOFT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use the configuration location and command transport supported by your MCP host. If it cannot find npx, supply the absolute path to your Node.js installation's npx executable.

URL scans may take up to 90 seconds. Where your client supports it, set its MCP request timeout to at least 120 seconds. The adapter's HTTP timeout defaults to 110 seconds and can be configured with GRIDINSOFT_TIMEOUT_MS (a positive integer in milliseconds). The adapter does not automatically retry requests, because a submitted scan may have already consumed credits. After a timeout, check the Inspector dashboard before submitting it again.

Tools

Tool	Input	Purpose	Credits
`inspect_domain`	`{"domain":"example.com"}`	Available reputation score, verdict, categories, and report link	3
`check_domain_safety`	`{"domain":"example.com"}`	Alias for `inspect_domain`	3
`get_domain_reputation`	`{"domain":"example.com"}`	Alias for `inspect_domain`	3
`scan_url`	`{"url":"https://example.com/login"}`	Page metadata and available security signals; additional analysis depends on the plan	10
`get_balance`	`{}`	Remaining credits and subscription status	Free

An Unknown verdict means no assessment is available; it does not mean the target is safe. Tool execution errors return isError: true, with an explanation in content. Discovery or prompt/resource failures surface as MCP errors.

Prompts and resources

check-website-safety requires the site argument (a URL or domain).
verify-domain-trust requires the domain argument.
gs://guide/threat-categories describes the security and content categories. A content category alone does not establish malware or fraud.

Example prompt arguments:

config.json

{
  "name": "check-website-safety",
  "arguments": { "site": "https://example.com" }
}

Command-line use

With GRIDINSOFT_API_KEY set in your environment:

Terminal

npx -y @gridinsoft/mcp-inspector check example.com
npx -y @gridinsoft/mcp-inspector inspect example.com
npx -y @gridinsoft/mcp-inspector scan https://example.com/login
npx -y @gridinsoft/mcp-inspector --help

Commands print the JSON tool result and exit with a nonzero status on failure. Running without arguments starts the stdio MCP server when launched by a client.

Plans

New accounts receive 100 free API credits per month. See the Inspector dashboard for current plans and pricing.

Development

Terminal

npm ci
npm test
npm run build
npm pack --dry-run

The tests cover MCP initialization, discovery, prompt argument forwarding, resources, tool aliases, authentication errors, HTTP failures, cancellation, timeouts, stdio framing, and CLI exit codes. An additional backend integration fixture can be run against an Inspector checkout with Composer dependencies installed:

INSPECTOR_TEST_ROOT=/absolute/path/to/inspector node --test test/php-integration.cjs

This fixture starts a temporary localhost PHP server, uses the real MCP routes/controller, and makes only public or unauthenticated requests. It does not load the application's environment file or perform paid scans.

License

MIT