Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jev-explorer Go to example.com and find the minimum cancellation notice for video appointments."
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.
Delegate browser exploration to Jev. Get back concise findings, source evidence, and a browser session you can inspect and continue.
Jev Explorer is an MCP server for agents that should spend less context on routine browser navigation. Give it an objective rather than a sequence of clicks. It explores with TypeSafe's Jev, retains progress, and hands control back when it finds evidence or needs help.
Early prototype. It is built on the pinned @tontoko/jev-browser engine. It does not claim universal browser reliability or a measured speedup over other agents.
Explores toward a natural-language objective and extracts previously unknown answers with verbatim source context.
Keeps the browser alive across missing-input handoffs and supervisor interventions.
Remembers findings, prior actions, observed outcomes, and supplied facts separately.
Returns a compact report instead of automatically sending the full DOM and trace to the supervising agent.
Stops on budgets, repeated actions without progress, validation problems, and uncertain submission outcomes.
Lets the supervisor inspect, act, continue, or close the same session.
Agent gives an objective
↓
Jev observes → chooses → acts → observes the effect
↓
Compact findings + evidence + retained browser
↓
Agent reviews, supplies missing information, or takes over
↓
Jev continues in the same sessionRelated MCP server: open-browser-control
Requires Node.js 24+. An API key is needed for Jev inference. Native inspection and supervisor actions do not call the model.
git clone https://github.com/lazyoft/jev-explorer.git
cd jev-explorer
npm ci --ignore-scripts
npx playwright install chromium
cp .env.example .envSet TYPESAFE_API_KEY in your local .env file. It is ignored by Git. The default model is jev-1.13.0; override it with JEV_MODEL when deliberately evaluating another version.
The browser engine comes from a pinned GitHub release archive. Its integrity is recorded in package-lock.json; see dependency provenance.
Use absolute paths in client configuration:
{
"mcpServers": {
"jev-explorer": {
"command": "node",
"args": [
"--env-file=/absolute/path/to/jev-explorer/.env",
"/absolute/path/to/jev-explorer/bin/jev-explorer.mjs"
]
}
}
}If your client already supplies the API key through its environment or secret manager, omit --env-file. No shell-profile reading, personal browser profile, Python launcher, or machine-specific configuration is required.
For Codex, the equivalent configuration is:
[mcp_servers.jev-explorer]
command = "node"
args = ["--env-file=/absolute/path/to/jev-explorer/.env", "/absolute/path/to/jev-explorer/bin/jev-explorer.mjs"]
startup_timeout_sec = 15
tool_timeout_sec = 240You can also start the stdio server directly:
node --env-file=.env bin/jev-explorer.mjsIt waits for MCP messages; it is not an interactive terminal chatbot.
Call jev_explore:
{
"url": "https://example.com",
"objective": "Find the notice required to cancel a video appointment without a charge. Do not submit any forms.",
"questions": [
{
"key": "notice",
"question": "Minimum cancellation notice for video appointments, verbatim including the unit."
}
],
"allowCommit": false
}The question defines what to discover, not the expected answer. The report includes the observed text, surrounding context, source URL, remaining issues, and a sessionId.
When the task needs information that was not supplied, use jev_continue:
{
"sessionId": "SESSION_ID_FROM_THE_PREVIOUS_RESULT",
"note": "The missing email is now available. Continue the existing draft.",
"values": { "email": "example@example.invalid" }
}Input values come from the caller or observed sources. Jev chooses controls and values; it does not generate free-form prose. This prototype asks the supervising agent when it needs a new string rather than guessing it.
Tool | Purpose |
| Open a dedicated session, optionally headed for manual authentication, without inference |
| Explore toward an objective and return a compact handoff |
| Resume the same objective with missing values, notes, or sourced facts |
| Inspect the session; request target references or a screenshot explicitly |
| Perform one supervisor-directed native action without Jev |
| Close the browser while retaining local evidence |
Status | Meaning |
| Source evidence is available, or the supervisor confirmed an effect. This is not certified business correctness. |
| A required value is still missing during the workflow. |
| Validation, ambiguity, lack of progress, an uncertain effect, or another issue needs attention. |
| The configured model budget was reached; the browser remains available. |
| The live browser no longer exists. Its trace is not a resumable browser session. |
workflowOutcome preserves the underlying workflow result separately. Finding one answer does not silently turn an incomplete workflow into a successful one.
When pendingEffect is true, inspect the outcome before retrying. The supervisor must explicitly resolve it with effectResolution: "confirmed" or "not_applied" and an evidence-backed note. Confirming an effect does not replay it.
Reports are normally limited to about 6,500 characters. Full traces and screenshots stay in a private local run directory. Target lists and screenshot payloads are opt-in.
Runs default to $XDG_STATE_HOME/jev-explorer/runs, or ~/.local/state/jev-explorer/runs. Override this with JEV_EXPLORER_RUNS. Sessions live in one MCP server process and expire after 30 minutes of inactivity. A server restart preserves files, not browser memory or cookies.
allowCommit defaults to false. The built-in guards are conservative heuristics, not a security boundary or a universal read-only mode. Browser controls can have unexpected effects. Use appropriately restricted accounts and only delegate authorized work.
Page text and evidence may contain sensitive information and may be sent to TypeSafe as decision context. Do not publish run directories. See security and data handling.
Current limitations include non-standard widgets, values represented as selected tokens, visual-only interfaces, and incomplete modelling of application-specific dependencies. The server exposes dedicated browsers, not automatic attachment to personal browser profiles.
npm run checkTests use real local browsers, synthetic applications, deterministic model decisions, and independent checks of saved records. No API key is needed for the default suite.
For an opt-in test with actual Jev calls:
node --env-file=.env --test --test-concurrency=1 --test-timeout=120000 test/live.mjsThis makes paid API calls using synthetic local data. It does not run in CI or use real accounts. Local results are not a benchmark of arbitrary websites.
Contributing · Architecture · Changelog
Apache-2.0. See LICENSE and NOTICE. The hosted TypeSafe service and Jev model weights are not included. This is an independent project built on third-party software and services.
Take one explicit native browser action in the retained session, with no Jev call. Use a current ref from jev_inspect. For typing provide the text; passwords are not returned in the handoff. Then continue the exploration with jev_continue. This tool does not generate selectors or execute arbitrary JavaScript.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| sessionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior, but the description adds critical context: it takes exactly one action, cannot generate selectors, and passwords are not returned. This goes beyond the annotations by explaining execution constraints. Minor gap: does not detail side effects of each action type, but annotations cover the destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each packed with essential information: the action scope, the ref requirement, the text instruction, the password caveat, and the follow-up with jev_continue. The negative constraints are front-loaded, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the action parameter with multiple command types, the description covers the common usage pattern and constraints clearly. The schema fully defines the action variants, so the description need not repeat them. A minor gap is not explaining when to use jev_act vs. jev_explore, but the description's focus on 'explicit' action and the follow-up with jev_continue implies the distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and there are no parameter descriptions in the schema. The description compensates by explaining the 'action' parameter's structure (commands like typing, clicking) and the need for a current ref from jev_inspect. It also mentions the text field for typing. However, it does not enumerate all possible commands, relying on the schema's oneOf, but the description provides enough context for typical use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool performs one native browser action in the retained session, listing examples like typing and noting it does not generate selectors or execute JavaScript. This clearly distinguishes it from exploration tools like jev_inspect and jev_continue. The verb 'take' with resource 'native browser action' is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit instructions: use a current ref from jev_inspect, provide text for typing, and then continue with jev_continue. It also warns that passwords are not returned in the handoff, guiding the agent on what to expect. This covers when to use and how to sequence with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the browser session and retain its local evidence. Closing does not undo business effects. A closed session cannot be resumed by replaying its trace.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as destructive and open-world. The description adds meaningful behavioral detail beyond those hints: local evidence is retained, business effects persist, and replaying the trace will not resume the session. This gives the agent a much fuller picture of consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly scoped sentences with no filler. The core action is front-loaded, followed only by high-value consequences. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description adequately covers purpose, side effects, and irreversibility. It omits details like idempotency or error behavior, but these are not essential given the simplicity and the annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions sessionId or how to identify the target session. The schema's property name and UUID format carry the meaning, but the description does nothing to compensate for the missing documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Close the browser session.' It adds distinctive constraints—evidence is retained, business effects are not undone, and the trace cannot be replayed—which clearly separates it from sibling tools like jev_open and jev_continue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical context: closing is final and does not reverse side effects, and a closed session cannot be resumed via replay. This implies when not to use the tool, although it does not explicitly name alternative tools such as jev_continue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Continue the same objective in the same live browser. Add missing values, a supervisor note or sourced facts. Keeps discoveries and prior effects and does not replay the whole workflow. Input values should be supplied data, not guessed answers.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| facts | No | ||
| values | No | ||
| sessionId | Yes | ||
| effectResolution | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as non-read-only, open-world, and destructive, so the description does not need to restate safety traits. It adds valuable behavioral nuance by explaining that discoveries and prior effects are preserved and that the workflow is not replayed. The instruction that input values should be supplied data, not guesses, is additional meaningful guidance. No contradiction with 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of three short, purposeful sentences. The primary purpose is front-loaded, and each sentence contributes meaning: what the tool does, what state it preserves, and what kind of input is acceptable. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, nested objects, no output schema, and destructive annotations, the description covers the main purpose and persistence semantics but leaves gaps. sessionId and effectResolution are not semantically explained, and there is no guidance on expected results or how the continuation appears to the caller. The annotations handle the safety profile, making this adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must carry the burden. It does explain the intended meaning of values, note, and facts, and clarifies that values should be real supplied data. However, it does not explain the required sessionId parameter or the meaning of effectResolution (confirmed/not_applied), leaving those under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states a specific verb and resource: continue the same objective in the same live browser, adding missing values, a note, or sourced facts. The mention of not replaying the whole workflow distinguishes it from a fresh start, and it contrasts naturally with sibling tools like jev_open, jev_explore, or jev_act that perform new actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful context: use this when continuing an existing objective rather than starting over, and when you need to supply concrete data, notes, or facts. It even warns against guessed answers. However, it does not explicitly name sibling alternatives or state clear when-not-to-use conditions, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delegate a complete browser exploration objective to Jev. Supply questions whose answers are unknown; answers include verbatim source evidence. Returns a compact handoff, not the full DOM. The browser stays open for inspection and continuation. ready_for_review is evidence for the caller to review, not certified business correctness. Use only within the user-authorized scope. Default submission guards are conservative heuristics, not a read-only security boundary.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| headed | No | ||
| values | No | ||
| maxCalls | No | ||
| maxSteps | No | ||
| maxTokens | No | ||
| objective | Yes | ||
| questions | No | ||
| sessionId | No | ||
| timeoutMs | No | ||
| allowCommit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive, open-world, non-read-only behavior, and the description honestly reinforces this with 'Default submission guards are conservative heuristics, not a read-only security boundary.' It also discloses return behavior, session continuation, and review semantics beyond the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but tightly packed, with the core purpose front-loaded in the first sentence. Each sentence contributes a distinct point: purpose, question semantics, output format, continuation, and safety caveats. It loses a point only because several important caveats are compressed into a single running paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no output schema, nested objects, and destructive annotations, the description is only partially complete. It explains the high-level contract and safety posture but omits operational details such as how to configure session continuation, what `values` or `allowCommit` affect, and the exact structure of the returned handoff.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only loosely covers `objective` and `questions`. The other nine parameters, including `url`, `values`, `sessionId`, `timeoutMs`, `maxCalls`, `maxSteps`, `maxTokens`, `allowCommit`, and `headed`, receive no semantic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly names the action: 'Delegate a complete browser exploration objective to Jev' and explains the core mechanism of supplying unknown questions with verbatim evidence. It also distinguishes itself from simpler browser tools by noting it returns 'a compact handoff, not the full DOM' and that the browser stays open. However, it does not explicitly name or differentiate sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: for complete exploration objectives and questions whose answers are unknown. It also warns to stay 'within the user-authorized scope' and clarifies that ready_for_review is evidence, not certified correctness. It lacks an explicit when-not-to-use or alternative selection compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a retained session with no model call. Default output stays compact. Request targets only when taking over; use nextOffset to page through targets. Request screenshot explicitly to receive the image. Refs become stale when the page changes.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| targets | No | ||
| sessionId | Yes | ||
| screenshot | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses that no model call is made, that output is compact by default, and that refs become stale when the page changes. These are valuable behavioral traits that an agent needs to know and are not inferable from the schema or annotations alone. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each packed with information: purpose, default behavior, parameter usage, and a warning. No filler. The key differentiator ('no model call') is front-loaded, and the warning about stale refs is placed at the end as a natural caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only inspection tool with no output schema, the description covers the essential usage: what it does, how to get targets and screenshots, and the lifecycle caveat about refs. The schema handles parameter bounds (offset max 1000) and defaults. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It does so for three of the four parameters: 'offset' is implied by 'use nextOffset to page through targets' (though the name mismatch could confuse), 'targets' is explained as 'only when taking over', and 'screenshot' as 'Request screenshot explicitly'. sessionId is self-evident from the parameter name and format. This compensates for the missing schema descriptions, but the 'nextOffset' wording introduces a slight inconsistency with the actual parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Inspect') and resource ('a retained session') and immediately clarifies a key distinction: 'no model call'. This differentiates it from sibling tools like jev_act or jev_continue. The phrase 'retained session' makes the target unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear conditions for optional parameters: 'Request targets only when taking over' and 'Request screenshot explicitly'. It also gives a pagination hint with 'use nextOffset to page through targets' and warns about stale refs. However, it does not explicitly name sibling tools or state when to prefer this over jev_explore or jev_continue, so the guidance is context-specific rather than comparative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an isolated browser session without inference. Use for authentication or to inspect the initial page before delegating a goal. A headed session can be operated by the user. The session stays alive until closed or idle expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| headed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=true), the description adds meaningful behavior: 'The session stays alive until closed or idle expiry' and 'A headed session can be operated by the user.' It also clarifies it performs no inference, which is a key behavioral trait. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core action and then usage and behavior. No filler; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers purpose, usage, and session lifecycle. It mentions idle expiry and user interaction, which are critical for correct invocation. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It indirectly explains url by describing use cases involving a page, and explicitly explains headed: 'A headed session can be operated by the user.' While it doesn't detail url format (already provided by schema's uri format), it adds useful context for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Open an isolated browser session without inference,' with explicit use cases ('for authentication or to inspect the initial page'). It distinguishes from siblings by highlighting 'without inference,' which contrasts with likely inference-based tools like jev_inspect or jev_explore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it: 'for authentication or to inspect the initial page before delegating a goal,' and implicitly excludes inference tasks via 'without inference.' However, it does not name sibling alternatives directly, leaving some inference about which tools to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0jev_actjev_closejev_continuejev_explorejev_inspectjev_openScored across 6 tools
Each tool has a clearly distinct role in the browser session lifecycle: open creates, inspect observes, explore delegates, continue extends, act manually intervenes, and close terminates. The descriptions reinforce these boundaries well, so an agent should have little trouble selecting the right tool.
All tool names follow the same 'jev_' prefix plus a single lowercase verb pattern. This is fully consistent and makes the action of each tool predictable from its name.
Six tools is well-scoped for a browser exploration server. Each tool covers a necessary part of the workflow without redundancy or bloat.
The tool set forms a complete lifecycle: open a session, inspect it, delegate exploration, continue with additional input, act manually when needed, and close the session. There are no obvious dead ends or missing operations for the stated purpose.
Autonomous cloud agent tasks: real browser + your tools, structured evidence-backed results.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
Real Chrome for agents: start a browser, read pages as numbered markdown, click, type, hand off.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.