How do I use Jev Guard MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Jev Guard MCP preview the Headless browser Wikipedia article and suggest a link to follow" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Jev Guard MCP

by RanielliMontagna

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Jev Guard MCP is an experimental, browser-only MCP server that lets Jev choose among code-owned navigation options without handing browser control to the model.

Codex provides intent. Playwright observes a fresh public browser context. The policy engine reduces the page to safe links. Jev selects one bounded ID. The trusted MCP client shows the proposed action and obtains human approval before calling execute.

Resumo em português: o Jev Guard conecta Codex, Jev/TypeSafe e Playwright dentro de um limite explícito. O modelo escolhe somente links produzidos pelo código. O cliente MCP confiável deve mostrar origem, rótulo e destino e obter aprovação humana explícita antes de executar; o servidor não comprova essa aprovação.

Why this exists

Computer-use agents are powerful precisely where mistakes are expensive: they can inherit sessions, interpret hostile pages and turn ambiguous model output into side effects. Jev Guard explores a narrower architecture:

use Jev for fast semantic judgment;
keep authority, URL policy and freshness checks in deterministic code;
isolate the browser from the user's Chrome profile and environment secrets;
make the proposed action inspectable before execution;
refuse authentication, forms, downloads and transactional flows.

Related MCP server: Playwright MCP

How it works

flowchart TD
    C[Codex provides URL and goal] --> P[Playwright opens an isolated public page]
    P --> S[Policy engine builds safe same-origin candidates]
    S --> J[Jev chooses a code-owned candidate ID]
    J --> H{Human approves exact action?}
    H -->|No| X[Cancel token and close browser]
    H -->|Yes| F[Re-observe and verify freshness]
    F --> N[Navigate to the exact approved URL]
    N --> Z[Verify postcondition and close browser]

The model never emits selectors, coordinates, JavaScript or arbitrary URLs. The executor accepts only a fresh, single-use preview token.

Approval flow

A trusted MCP client is responsible for showing the source, label and destination and obtaining explicit human approval before calling jev_guard_execute. Possession of a preview token is the technical authorization to execute; the server cannot independently attest human approval. Keep tokens private to the trusted client. The workflow is preview → human approval → execute.

jev_guard_preview opens the source page and returns a proposal without navigating to the proposed destination:

{
  "status": "ready",
  "sourceUrl": "https://en.wikipedia.org/wiki/Headless_browser",
  "confidence": 1,
  "action": {
    "id": "link_3",
    "label": "web browser",
    "destination": "https://en.wikipedia.org/wiki/Web_browser"
  },
  "usage": {
    "attempts": 1,
    "model": "jev-1.13.0"
  }
}

After human approval, jev_guard_execute consumes the token before attempting the exact navigation. jev_guard_cancel consumes it without navigating.

Safety boundary

Allowed	Intentionally unsupported
Public HTTPS pages	Authenticated accounts and private pages
Visible, same-origin links	Typing, forms, buttons and uploads
Query-free, low-risk GET navigation	Login, OAuth, purchase, deletion or confirmation
Fresh isolated Chrome contexts	Personal Chrome profiles, cookies or local storage
One approved navigation per token	Downloads, native apps and whole-computer control

Additional controls include:

JavaScript and WebSockets disabled in the page context;
localhost, private networks and private DNS resolutions blocked;
exact main-document URL enforced before network access and after navigation;
every HTTPS request fetched with redirects disabled; all 3xx responses and subframe documents blocked;
page text and goals redacted before TypeSafe calls;
minimum effective confidence of 0.80;
tokens stored only in memory, single-use and valid for 120 seconds;
capacity reserved before browser/model work, including consumed executions; shutdown closes active browsers;
bounded public MCP error codes and messages, with no dependency call logs;
TypeSafe model pinned to jev-1.13.0, with response validation and no automatic retries.

Read the full architecture and threat model, including the documented DNS-rebinding, adversarial-content and GET-side-effect risks.

Quickstart

Requirements: Node.js 22+, Google Chrome and a TypeSafe API key.

git clone git@github.com/raniellimontagna/jev-guard-mcp.git
cd jev-guard-mcp
npm ci --ignore-scripts
npm test
npm run typecheck
npm run build

The server reads TYPESAFE_API_KEY from the process environment. On macOS, scripts/run-from-keychain.sh can load it from a Keychain item whose service is typesafe-api-key, without placing the value in Git or MCP configuration.

./scripts/run-from-keychain.sh

Candidate Codex configuration, after replacing the command with the absolute path of your clone:

[mcp_servers.jev_guard]
command = "/absolute/path/to/jev-guard-mcp/scripts/run-from-keychain.sh"

Registering the server is deliberately separate from cloning it. Review the security boundary first and restart Codex after changing MCP configuration.

MCP tools

Tool	Effect
`jev_guard_preview`	Opens a public source page and returns one bounded proposal plus a short-lived token. It does not navigate to the proposal.
`jev_guard_execute`	Consumes a fresh token and performs exactly one approved navigation.
`jev_guard_cancel`	Consumes a pending token and closes its isolated browser without navigating.

Verification

The repository test suite covers URL policy, DNS/private-network rejection, redaction, candidate extraction, Jev response validation, token lifecycle, stale-page rejection, shutdown and MCP schemas.

A public smoke test is available:

npm run smoke:live
npm run smoke:live -- --execute

The executing form performs one bounded Wikipedia navigation and incurs a TypeSafe call. It never prints the credential or preview token.

Verified public route on 2026-09-20:

Headless browser → web browser → Web browser
https://en.wikipedia.org/wiki/Headless_browser
https://en.wikipedia.org/wiki/Web_browser

Development

npm test
npm run typecheck
npm run build
npm audit --omit=dev
npm audit signatures
npm pack --dry-run

Contributions should preserve the code-owned action boundary. Expanding into authenticated pages, typing, forms or transactional actions requires a separate threat model and explicit confirmation design.

Status and license

Jev Guard MCP is experimental research software. It is not a general-purpose browser agent and should not be used for authenticated, private or high-consequence workflows.

Released under the MIT License.

Available Tools

3 tools

jev_guard_cancelCancel previewed Jev navigationA

Read-only

Consume a pending preview token without navigating and close its isolated browser.

ParametersJSON Schema

Name	Required	Description	Default
`token`	Yes	Single-use token returned by jev_guard_preview

TDQS

A3.5/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotation contradiction: readOnlyHint=true asserts the tool does not modify its environment, yet the description says it consumes (invalidates) a single-use token and closes an isolated browser — both are side effects on state. The description directly contradicts the annotation's safety claim, which is exactly the case the rubric flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One 14-word sentence that front-loads the primary action (consume token) followed by the secondary effect (close browser). Every word earns its place, and the most decision-relevant detail — 'without navigating' — is positioned early.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with annotations and no output schema, the core behavior is described adequately. However, edge cases are unaddressed (behavior on an already-consumed or invalid token, what the tool returns), and the readOnlyHint contradiction muddies what the agent should expect. Adequate with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the token parameter documented as a single-use token returned by jev_guard_preview plus a format pattern. The description's 'pending preview token' aligns with this and adds only marginal meaning (the pending state). Baseline 3 applies because the schema carries the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('consume a pending preview token', 'close its isolated browser') with a clear resource. The phrase 'without navigating' explicitly distinguishes it from the execute sibling, and the token provenance from jev_guard_preview is established in the schema. The cancel/preview/execute trio is fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear operational context: this is the path for not navigating, consuming the pending token and closing the browser. It implies it is the alternative to jev_guard_execute for aborting a preview, though it never explicitly names siblings or states when-not conditions. Clear context, but no explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jev_guard_executeExecute previewed Jev navigationA

Consume one preview token and perform exactly its fresh, same-origin navigation. A trusted MCP client must show the source, label and destination and obtain explicit human approval before calling execute. Possession of a preview token is technical authorization; the server cannot independently attest human approval.

ParametersJSON Schema

Name	Required	Description	Default
`token`	Yes	Single-use token returned by jev_guard_preview

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as non-read-only, non-idempotent, and non-destructive. The description adds meaningful behavioral context beyond those flags: the token is consumed, navigation is same-origin and fresh, and the server cannot independently verify human approval. This is genuinely useful and does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly worded sentences front-load the core behavior and then provide the critical human-approval caveat. Every sentence earns its place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter mutation tool with rich annotations, the description covers the action, the preview-token prerequisite, and the human-approval responsibility. No output schema is expected, and nothing essential for calling the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, token, is already fully documented in the schema with a pattern, required flag, and description. The tool description merely refers to it as a preview token and adds no new semantic detail, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action: 'consume one preview token and perform exactly its fresh, same-origin navigation.' It clearly identifies the resource and distinguishes this tool from the preview and cancel siblings by framing it as the execution step after preview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: a trusted MCP client must show source, label, and destination and obtain explicit human approval before calling execute. It does not explicitly name the alternative tools, but the preview-token prerequisite makes the intended workflow clear enough for an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jev_guard_previewPreview safe Jev navigationA

Read-only

Open a public HTTPS page in a fresh browser profile and ask Jev to preview one same-origin, query-free link. This tool never executes the proposed navigation.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	Public HTTPS page to inspect
`goal`	Yes	What information or destination should be found

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only and non-destructive behavior, but the description adds valuable behavioral details beyond that: it launches a 'fresh browser profile', restricts to 'public HTTPS page', and previews only 'one same-origin, query-free link'. These are meaningful constraints not present in the annotations, enhancing transparency about side effects and scoping.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two precise sentences front-load the core action and the critical non-execution behavior. There is zero fluff; every clause adds essential information. The structure is ideal for quick parsing by an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read-only tool, the description covers the primary behaviors and constraints. It does not describe the return value or expected output format, but since no output schema exists, this is a minor gap. The 'fresh browser profile' and 'never executes' details give a solid picture of what the agent needs to know to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes both parameters (url and goal) with 100% coverage. The description adds some context by explaining how they are used ('ask Jev to preview one... link' guided by goal), but it does not significantly expand on format, constraints, or interaction beyond what the schema provides. The description's mention of 'same-origin, query-free' is an operation-level constraint rather than parameter-level detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('Open a public HTTPS page... ask Jev to preview') and the exact resource ('one same-origin, query-free link'). It explicitly states 'never executes the proposed navigation', which differentiates it from the sibling tool jev_guard_execute. The purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: this tool previews a link without executing it, implying it should be used when a safe, non-committing check is needed. It does not explicitly name jev_guard_execute or jev_guard_cancel as alternatives, but the contrast with 'never executes' is strong enough that an agent can infer the appropriate use case. Lacks explicit exclusion or alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0Sep 20, 2026
- First observedjev_guard_cancel
- First observedjev_guard_execute
- First observedjev_guard_preview

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-09-20 19:10 across 3 tools

Disambiguation5/5

Each tool maps to a distinct state in the preview lifecycle: creating a preview, executing it, or canceling it. The descriptions make it clear that preview never navigates, execute does navigate, and cancel aborts without navigating.

Naming Consistency5/5

All tools share the jev_guard_ prefix and follow the same lowercase verb pattern: preview, execute, cancel. The naming convention is uniform and predictable.

Tool Count5/5

Three tools is exactly the right scope for this guard workflow: one to create a preview token, one to consume it via navigation, and one to consume it by canceling. There is no redundancy or bloat.

Completeness5/5

The preview-to-execute-or-cancel lifecycle is fully covered with no dead ends. Each preview token has a clear path to either execution or cancellation, which satisfies the server's stated purpose.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Oya Browser
io.github.OyadotAI
Real Chrome for agents: start a browser, read pages as numbered markdown, click, type, hand off.
Browser Automation Agent Orchestration
1
playwright-mcp-server A
com.thenextgennexus
Headless browser primitives for AI agents when sites need real JS rendering.
Browser Automation Web Scraping
175
agent-web-actions
com.trycloudflare.plates-spread-materials-optimum
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Browser Automation Agent Orchestration
2
agent-web-actions
com.trycloudflare.clients-involving-billion-headers
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Browser Automation Web Scraping
2

Related MCP Servers

browser-mcp-claude
Browser Automation Agent Orchestration
saGoldberg31
F
license
Not graded
quality
C
maintenance
Enables remote browser automation via MCP, allowing models to open pages, read snapshots, click, fill, and select elements using Playwright, with built-in security restrictions against sensitive actions.
Updated a month ago (2026-08-21 08:03 UTC)
-
Playwright MCP
Browser Automation Web Scraping
1000carlospena-prog
A
license
B
quality
C
maintenance
Enables LLMs to drive a hosted headless Chromium browser over HTTP, performing navigation, clicks, typing, and page reading through accessibility snapshots, protected by bearer-token authentication.
Updated 21 days ago (2026-08-31 20:01 UTC)
23
5,046,799 npm
Apache 2.0
browser-use-mcp
Browser Automation Web Scraping
jimsimoy
A
license
Not graded
quality
C
maintenance
Provides AI clients with deterministic Playwright-driven browser control, enabling navigation, interaction, screenshots, and inspection of rendered HTML, computed styles, console diagnostics, and font audits without an embedded LLM or API key.
Updated 11 days ago (2026-09-10 11:22 UTC)
MIT
ultrabrowse
Browser Automation Agent Orchestration
narekgevorgyan
A
license
A
quality
C
maintenance
Enables AI agents to delegate complex web browsing goals to a real Chrome instance driven by Jev, completing tasks end-to-end in ~300ms per decision and returning only the final result.
Updated 2 days ago (2026-09-19 11:36 UTC)
11
1
MIT