How to Use Jev in Cursor: Rules, Skills and a Thin MCP Wrapper
Cursor is a code editor with an agent attached, and that agent has four places where instructions and integrations live: project rules in .cursor/rules, an AGENTS.md file, agent skills under .cursor/skills, and MCP servers in mcp.json. This page is about what goes into each of those four places when the thing you are integrating is the jev api — a model that answers typed questions about a state instead of generating prose.
Provenance: every Cursor behaviour below comes from Cursor’s own documentation (
cursor.com/docs/rules,/docs/skills,/docs/mcp, read 2026-11-12). Every TypeSafe behaviour, threshold and answer value comes fromdocs.typesafe.ai(introduction/coding-agents,agent-skill,introduction/quickstart,models,confidence,primitives/choice,changelog, read the same day). Nothing on this page is an invented illustration. Where a number appears, it is the number in the source.
First: what Cursor can and cannot do with Jev
TypeSafe’s coding-agents page is unusually direct about this, and getting it wrong costs days:
Jev is not a drop-in replacement for the LLM behind Claude Code, Cursor, opencode, Copilot, Muse Spark, Grok Bot, or similar tools.
The reason is structural. Cursor’s agent streams text, calls tools and edits files on natural-language instructions. Jev does none of that — it takes a state and a set of typed questions and returns one answer per question, constrained to the options you supplied. There is no Cursor model dropdown entry that swaps the agent’s brain for Jev, and no model: "jev-latest" line that changes how the editor behaves.
What you actually want, in TypeSafe’s own words, depends on which of four things you were trying to do:
| You wanted to… | The documented path |
|---|---|
| Make Cursor better at writing code that calls TypeSafe | Install the TypeSafe agent skill. It carries the question types, the patterns and the request-shaping rules, so the agent generates correct integrations |
| Use Jev inside an app or agent you are building — routing, classification, scoring, guardrails | Start from the Quick start, then the primitives reference and the patterns |
| Swap out the model that powers Cursor’s agent | Jev is not the tool for this. Keep an LLM-based agent and use Jev separately |
| Try Jev before writing any code | The Playground: paste a state, add questions, read answers |
Everything below is the first and second rows. The third row is a dead end and the fourth row needs no integration.
The four surfaces, and what each one is for
| Surface | Where it lives | What it is good for with Jev | What it cannot do |
|---|---|---|---|
| Project rules | .cursor/rules/*.mdc (version-controlled) | Standing conventions: where the question constants live, what the thresholds are, how to log answers | Cannot carry executable code; a file mention like @template.py is a pointer the agent reads with its tools, not inlined content |
AGENTS.md | project root and any subdirectory | The same conventions in plain markdown, no frontmatter, no metadata | No glob scoping, no manual-only mode |
| Agent skills | .agents/skills/, .cursor/skills/, ~/.agents/skills/, ~/.cursor/skills/ | A folder with SKILL.md plus scripts/, references/, assets/ — the place to ship the actual Jev calling code | Loaded on demand, so it is not a guarantee; the agent decides relevance |
| MCP server | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) | A process exposing a judge tool the agent can call in any turn | Requires you to write and host the server; there is no TypeSafe one to install |
A rule, a skill and an MCP server are not competing options. The clean setup for a Jev project uses a rule for the conventions, a skill or plain module for the code, and — only if you want the decision available without the agent writing a call site — an MCP wrapper.
Rules: the frontmatter matrix decides when it loads
Project rules must use the .mdc extension. Cursor’s docs are explicit that a plain .md file inside .cursor/rules is ignored by the rules system, because it has no frontmatter to carry description, globs and alwaysApply. If you prefer plain markdown, use AGENTS.md instead.
Three fields interact to decide when a rule is included:
alwaysApply | description | globs | Behavior |
|---|---|---|---|
true | — | — | Always included; globs and description are ignored |
false | — | provided | Auto-attached when a matching file is in context |
false | provided | omitted | Agent reads the description and pulls the rule in when relevant |
false | omitted | omitted | Included only when you @-mention the rule |
For a Jev integration, the second row is the one you want. Your code calls Jev from specific files — an api/ package, a judgments/ module — and only those edits need the rule burning context. A rule like this attaches itself when you touch that directory:
---
description: Conventions for calling the jev api from this repo's judgment layer
globs: src/judgments/**/*.py, src/api/**/*.py
alwaysApply: false
---
- All question ids, criteria and thresholds live in `src/judgments/questions.py`.
Never inline a dictionary of options at a call site.
- Every call sends a state plus a map of questions; treat the response as typed
data, not as text to parse.
- Branch on `probabilities[choice]` for Choice answers and on the Noul value
itself. Do not invent a second confidence check for Choice.
- Log the answer id, the chosen option and the probability. Never log the API key.
Two things in that rule matter more than the rest. First, the single-module rule is not arbitrary: Cursor’s docs recommend putting constants in one place for reviewability, and TypeSafe’s agent-skill page makes the same point from the other side — “put the constants (questions and thresholds) in a single place so they’re easy to review”, adding that agents are not great at writing questions, so expect to edit collaboratively.
Second, the threshold guidance is a real correction to the obvious instinct. TypeSafe’s agent-skill page lists “you’re using confidence thresholds everywhere” as a common problem, and the fix is: for a Noul, threshold the value; for a Choice, threshold probabilities[choice]; reserve confidence for Score answers where it detects a split across distant levels.
Glob patterns that actually scope
Cursor documents these pattern forms, and they behave the way you would expect from gitignore-style globs:
| Pattern | Matches |
|---|---|
* | Any single file name segment |
** | Any number of directories (recursive) |
*.ts | All .ts files in the root |
**/*.ts | All .ts files in any directory |
src/** | All files anywhere under src/ |
docs/**/*.md, docs/**/*.mdx | .md and .mdx under docs/, comma-separated |
What Cursor says to leave out of a rule
The docs list four things to avoid, and all four apply to Jev rules: copying entire style guides (use a linter), documenting every possible command (the agent knows npm, git and pytest), adding instructions for rarely-applied edge cases, and duplicating what is already in the codebase instead of pointing at a canonical example. Rules should stay under 500 lines, and large ones should be split.
Precedence, and why it matters for a team
Rules are applied in the order Team Rules → Project Rules → User Rules, all applicable rules merged, with earlier sources winning conflicts. So an enforced team rule — “all Jev calls go through src/judgments/client.py” — cannot be switched off by a member’s personal rule, and a personal rule about Jev cannot override it either. Admin-side, Team Rules are set from the dashboard with an “Enforce this rule” switch; when it is off, team members can disable the rule in Customize.
AGENTS.md, including the nested form
AGENTS.md is a plain markdown file with no metadata. In a Jev repo it is the right home for short, readable conventions when you do not want to maintain .mdc frontmatter:
# Project Instructions
## Judgment layer
- Jev answers questions; it does not write code. Do not ask it to.
- Call site: `src/judgments/client.py`. Question constants: `src/judgments/questions.py`.
- Noul: act above 0.7, escalate below 0.3, and give 0.3–0.7 its own branch.
Cursor supports AGENTS.md in the project root and in subdirectories, and nested files combine with the parent directories, with the more specific instructions taking precedence. In a monorepo that maps neatly onto several judgment layers: services/billing/AGENTS.md can carry billing’s option names and thresholds while the root file carries the general rule.
Skills: where the executable part goes
Agent Skills is an open standard, and Cursor discovers skills from four locations: .agents/skills/ and .cursor/skills/ at project level, ~/.agents/skills/ and ~/.cursor/skills/ for the local machine. For compatibility it also loads skills from .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/ — which is why one well-built skill can serve Cursor, Claude Code and Codex from a single directory.
The structure Cursor expects:
.cursor/skills/
└── jev-judgments/
├── SKILL.md
├── scripts/
│ └── judge.py
└── references/
└── QUESTIONS.md
SKILL.md carries YAML frontmatter. The fields that matter:
| Field | Required | Effect |
|---|---|---|
name | Yes | Lowercase letters, numbers, hyphens; must match the parent folder name |
description | Yes | What the skill does and when to use it — this is what the agent matches against |
paths | No | Glob patterns scoping the skill to matching files; comma-separated string or list |
disable-model-invocation | No | true makes it a slash-command-only skill, never auto-applied |
icon, color | No | Badge styling when the skill backs a Custom Mode |
Note the deprecation detail: the legacy globs field is still accepted as a fallback, but new skills should use paths. If you copy a skill written for an older host, that is the field to update.
A Jev skill is small, because the heavy part is the script:
---
name: jev-judgments
description: Call the jev api to make a bounded judgement about a file, diff or
ticket — one Choice, Score or Noul question, with probabilities returned.
paths:
- "src/judgments/**"
---
# Jev judgments
Run `scripts/judge.py` with a question id from `references/QUESTIONS.md`.
## Instructions
- Read `references/QUESTIONS.md` before adding a question. Options are fixed there.
- Pass the state as a file path or `-` for stdin; never retype the text into the script.
- The script prints one JSON object. Branch on `probability` for Choice answers.
Two design notes worth carrying over from TypeSafe’s skill guidance. The description’s opening words are the trigger, so write a self-contained sentence rather than a generic label — TypeSafe’s docs give the condensed version of this as “self-contained trigger sentence in first 57 characters”. And when the skill ships a stale schema, the symptom is specific: the agent invents request or response fields. That failure mode is worth recognising, because the fix is an update, not a longer prompt.
If you have already accumulated dynamic rules and slash commands, Cursor ships /migrate-to-skills (documented as part of 2.4) which converts “Apply Intelligently” rules — alwaysApply: false and no globs — into skills, and slash commands into skills with disable-model-invocation: true. Rules with alwaysApply: true or explicit globs are deliberately not migrated, since their triggering conditions already differ from skill behaviour.
MCP: writing the wrapper yourself
Here is the part where most tutorials quietly invent something. TypeSafe does not publish an MCP server. As of 2026-11-12, the string MCP does not appear anywhere in TypeSafe’s full documentation bundle — docs.typesafe.ai/llms-full.txt, 1,359,974 bytes, zero word-boundary matches. Cursor’s MCP pages describe a protocol and a config format, not a TypeSafe server to install. So the honest integration is a thin server you write: one tool, one HTTP call.
Cursor’s config supports project scope and global scope, with different files: .cursor/mcp.json in the project for project-specific tools, ~/.cursor/mcp.json in your home directory for tools available everywhere. A stdio entry uses type, command, args, and optionally env and envFile:
{
"mcpServers": {
"jev": {
"type": "stdio",
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/jev_mcp_server.py"],
"env": { "TYPESAFE_API_KEY": "${env:TYPESAFE_API_KEY}" }
}
}
}
envFile is stdio-only — remote servers do not support it, and Cursor’s answer for those is config interpolation with variables from your shell profile. Interpolation works in command, args, env, url and headers, and ${workspaceFolder} resolves to the project root.
The server itself is short, because the MCP Python SDK derives the tool schema from type hints and the docstring. The shape below follows the two official sources exactly: the SDK’s MCPServer plus @mcp.tool() decorator, and TypeSafe’s request body from the Quick start.
# jev_mcp_server.py — stdio transport
import json
import logging
import os
import urllib.request
from mcp.server import MCPServer
# stdout carries JSON-RPC on stdio transports. Logs go to stderr instead.
logging.basicConfig(level=logging.INFO)
log = logging.getLogger(__name__)
mcp = MCPServer("jev")
ENDPOINT = "https://api.typesafe.ai/v1/systemone"
@mcp.tool()
def judge_choice(
state: str,
question_id: str,
instructions: str,
options: dict[str, str],
) -> dict:
"""Ask the jev api one Choice question about a state; return the choice, its probability and confidence."""
body = {
"model": "jev-latest",
"state": state,
"questions": {
question_id: {
"type": "choice",
"instructions": instructions,
"criteria": options,
}
},
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(body).encode(),
headers={
"Authorization": "Bearer " + os.environ["TYPESAFE_API_KEY"],
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request, timeout=30) as response:
payload = json.loads(response.read())
answer = payload["answers"][question_id]
choice = answer["choice"]
log.info("jev %s=%s p=%.3f", question_id, choice, answer["probabilities"][choice])
return {
"choice": choice,
"probability": answer["probabilities"][choice],
"confidence": answer["confidence"],
"usage": payload.get("usage", {}),
}
Three constraints are doing real work here and each has a documented source. The print() ban is Cursor-and-protocol level, not style: on stdio the JSON-RPC messages travel over stdout, and the MCP documentation says to never write there — use logging, which goes to stderr. The model: "jev-latest" string is the one TypeSafe’s own curl example sends. And answers being keyed by your question id is the documented contract — the model never sees the id, which is why the id you choose is what comes back.
One honest limit: the code above is assembled from those two official documents. It was not executed against a live TypeSafe key while writing this page, so treat it as a verified shape rather than a tested binary. The API endpoint, the header names, the jev-latest model string and the response structure are all quoted from source; your retry policy is not, and that is the part to add for production.
The numbers that belong in the rule, not in the prompt
A Cursor rule that says “check the confidence” produces code that checks the wrong number. These are the documented starting points, so put them in the rule body verbatim.
Noul. The value is the probability that the statement is true. TypeSafe documents 0.7 as a yes threshold and 0.3 as a no threshold, and says to give the 0.3–0.7 band its own outcome in code rather than rounding it to one side.
Choice. confidence is computed from the top probability, so a confidence threshold adds no second check. Threshold probabilities[choice] instead, which reads directly as “how likely is the selected option”. The documented mapping shows why an absolute number only means something relative to the option count:
| Options | Top probability that gives confidence 0.5 |
|---|---|
| 2 | 0.75 |
| 3 | 0.67 |
| 10 | 0.55 |
Score. Confidence carries information here that the position hides. With three levels, probabilities (0, 0.5, 0.5) give confidence 0.25 — torn between adjacent levels — while (0.5, 0, 0.5) gives 0, torn between opposite ends. The docs’ worked example, probabilities (0, 0.57, 0.43), yields about 0.35.
What a healthy answer looks like. The Quick start’s recorded response for one support ticket is a useful calibration reference: department came back technical at confidence 1.0 with probabilities 1.0/0.0/0.0; frustration scored 0.67 at confidence 0.5 with probabilities 0.33/0.67/0.0; is_urgent returned 0.99; usage read input_tokens 428 and output_tokens 73. TypeSafe notes those are example results and values can change between releases — which is exactly why the rule should not hard-code a claim about what will come back.
Cost. Every current model is priced at $42 per Btok, $0.042 per Mtok, paid on input only, with output tokens free. That is the number to put in a comment next to the batching decision: a request pays for the state once, however many questions ride along.
A checklist before you trust the integration
- The rule scopes by
globsand is notalwaysApply: trueunless the conventions genuinely apply to every file. - A plain
.mdfile in.cursor/rulesis either converted to.mdcor replaced by anAGENTS.md. - Question ids, criteria and thresholds live in one module that a reviewer can read in a single screen.
- The code branches on the Noul value and
probabilities[choice], not on a blanket confidence threshold. - If you wrote an MCP server: it logs through
logging, neverprint, and the API key arrives viaenvinterpolation rather than a committed string. - The
descriptionin a skill’s frontmatter opens with a self-contained trigger sentence, and the skill’s reference file lists the option names so the agent does not invent them. - Answer values in tests are recorded as fixtures with the model id they came from, since TypeSafe says values can shift between releases.
Where this does not help
If what you wanted was a faster or cheaper Cursor, none of the above changes that — Cursor’s agent still runs on its own model, and adding a Jev MCP server just gives it one more tool. If your decisions are open-ended (“write this refactor”), Jev’s answer space is the wrong shape and no amount of rule-writing fixes it. And if you are not prepared to review the question text yourself, a skill will happily generate plausible-sounding questions with the wrong option boundaries; TypeSafe’s own advice is to expect to edit them collaboratively rather than accept them at face value.