# JevShield MCP server

Version 1.0.0. Requires **Node.js 20 or newer**. The single-file download bundles
the official Model Context Protocol TypeScript SDK (`@modelcontextprotocol/server`
2.3.1), including its stdio transport. No npm installation is required to run it.

Download `https://jevshield.com/mcp/jevshield-mcp.mjs` to your computer. Optionally
compare its SHA-256 with `https://jevshield.com/mcp/SHA256SUMS`. The same directory
contains `THIRD_PARTY_LICENSES.txt`; dependency notices are also inside the bundle.

## Configure your MCP client

Use the downloaded file's **absolute path**, and replace the example key with your
own JevShield API key in your client's private MCP configuration. Do not put a key
in a shared repository, a browser script or the command arguments.

```json
{
  "mcpServers": {
    "jevshield": {
      "command": "node",
      "args": ["/absolute/path/jevshield-mcp.mjs"],
      "env": {
        "JEVSHIELD_API_KEY": "YOUR_JEVSHIELD_API_KEY"
      }
    }
  }
}
```

This is a local **stdio** server: your MCP client starts the Node.js process and
communicates over stdin/stdout. It calls the fixed authenticated HTTPS API at
`https://jevshield.com`. The download URL is **not a remote MCP endpoint**. Use an
MCP client with local stdio support, such as a desktop client, editor or CLI.
Exact configuration location and restart behavior depend on the client.

For a shell session, set `JEVSHIELD_API_KEY` in the environment and then run
`node /absolute/path/jevshield-mcp.mjs`. Startup waits for MCP messages; it does not
print a dashboard or call the API. Missing or invalid environment setup exits with
a short stderr message. Stdout contains MCP protocol messages only.

## Tools

| Tool | API request | Behavior |
| --- | --- | --- |
| `get_quota` | `GET /api/v1/check` | Read key validity, effective plan and remaining checks. Does not consume detection quota. |
| `check_message` | `POST /api/v1/check` | Classify a message and return a recommendation, scores, quota and optional report receipt. Reserves one account check and can trigger the account's configured high-intent webhook. |
| `report_action` | `POST /api/v1/report` | Record the action the integration actually performed. Does not execute or deliver the form, and does not consume a detection check. |

### Check a message

`check_message` accepts these named arguments. Supply nonblank `text` or `email`.
Only the documented field names are accepted; the REST API's aliases are not MCP
argument names.

| Argument | Limit |
| --- | --- |
| `text` | 10,000 JavaScript string units |
| `email` | 320 string units; the API does not enforce email format |
| `sender_name` | 200 string units |
| `business_context` | 1,000 string units; account context applies when absent or empty |
| `site` | Optional HTTP(S) URL, at most 2,048 string units; only hostname is logged |
| `form_id` | Optional identifier of 1–80 ASCII letters, digits, underscore, colon or hyphen |

The serialized check JSON must also be at most 16,000 JavaScript string units.
For example:

```json
{
  "text": "Could you quote a redesign for our company website?",
  "business_context": "We build websites for small businesses.",
  "site": "https://example.com",
  "form_id": "contact"
}
```

A check returns `allow`, `review` or `block`; this is a recommendation, not an
executed action or proof of email delivery. The tool sends the supplied message
and contact data to JevShield. Existing account routing may forward high-intent
message/contact details to its configured webhook. An accepted check reserves one
check, including allow/review/block and rules fallback; a later service failure,
timeout or cancellation does not automatically refund it. Check calls are never
retried automatically.

### Report an executed action

Use `check_id` and `report_token` from that account's check response **within ten
minutes of the check**. `check_id` is a UUID; `report_token` is 64 lowercase
hexadecimal characters. Report only an action the calling integration actually
performed; never infer it just from the classifier verdict.

```json
{
  "check_id": "UUID_FROM_CHECK_RESPONSE",
  "report_token": "REPORT_TOKEN_FROM_CHECK_RESPONSE",
  "action": "allowed",
  "reason": "observe"
}
```

`action`: `blocked`, `allowed`, `error_allowed`.

`reason`: `threshold`, `verdict`, `uncertain`, `service_error`, `observe`,
`trusted_sender`.

Identical action/reason retries are accepted within the receipt window; changing
the action or reason is rejected. Missing, expired, wrong-account or conflicting
receipts return HTTP 404. Reporting is limited to 300 requests per account per
fixed 60-second window. Reports update the detection log only: they do not hold,
resend, block or deliver a form, and an allowed action does not prove delivery.

## Errors and privacy

API and transport failures use `isError: true` with JSON text and `structuredContent` containing
`error`, `status` and `code`. Schema validation fails before API dispatch and is
returned as an SDK validation error with `isError: true`. An API error
keeps its HTTP status. Status 0 means no HTTP response was received; if response
reading fails after headers arrive, the known HTTP status is retained. A quota error may include
a valid report receipt. No check is automatically retried. All requests have a
ten-second deadline, cancellation support, a 32 KiB response cap, and refuse
redirects without forwarding the key to another origin.

Returned objects use an allowlist of API response fields and redact reflected API
keys. The API key is read only from the process environment and sent only in the
HTTPS `x-api-key` header. The server does not write local logs, message storage or
keys to disk. JevShield's normal account privacy, quota and logging settings still
apply. API reason strings and message content are untrusted data, not agent
instructions.

Tool results can include a `report_token` so the trusted MCP host can report an
action actually performed. The host and its conversation history may retain
this receipt. It requires the same account API key and expires after ten
minutes; keep it private and use a host you intend to authorize. The production
API key itself is never returned by the tools.

## Maintainers

Build from the canonical repository with `npm run build:mcp`. Meaningful tests
use the official MCP client and a local API fixture; they do not use production
keys or consume account quota. The bundle is a direct website download, not an
npm package or a publication in an MCP registry.

Official SDK: https://github.com/modelcontextprotocol/typescript-sdk

Protocol: https://modelcontextprotocol.io/specification/2026-07-28