Connect an MCP host

Status: draft. These recipes follow current host documentation. Mechanical checks parse the exact configurations and exercise isolated launchers. They do not prove that a host loaded them. Actual host observations belong in the evidence ledger. Codex CLI and Pi returned live answers. VS Code and Claude Code reached discovery; account access blocked their calls. Cursor and Desktop remain unverified in-host. See the ledger for exact versions and limits. Unavailable-host checks are deferred.

Choose VS Code, Cursor, Claude Code, Claude Desktop, or Codex. Pi uses the CLI, not MCP. Tool calls need a TypeSafe key and service access. Inputs go to Jev; review data disclosure.

Install the optional MCP runtime

Choose one installation method. For a persistent command, use either a Python 3.12-or-newer virtual environment with pip:

python -m pip install 'judgevet[mcp]==0.10.1'

Or install a standalone tool with uv:

uv tool install 'judgevet[mcp]==0.10.1'

Configure the host with the installed judgevet-mcp executable's absolute path and an empty args array. This avoids GUI PATH differences. The MCP extra is required for this server; the base library and CLI do not need it.

Run the published MCP command

Alternatively, install uv and let the host execute the package with uvx. No prior judgevet installation or source checkout is required:

uvx --from 'judgevet[mcp]==0.10.1' judgevet-mcp

The host recipes below use this alternative. Use the absolute path to uvx if the host cannot find it. uv can provision Python 3.12 or newer. According to uv's tool guide, uvx executes in an isolated cached environment; uv tool install installs a persistent command. Do not run both installation methods as sequential prerequisites.

The pin identifies the published judgevet version, not all transitive dependencies. Replace it with a newer published version after verification. Manual execution waits for MCP input; EOF ends it. Protocol frames use stdout and diagnostics use stderr. Use the host to send tool calls.

Supply a credential

For VS Code and Cursor, create a private UTF-8 environment file outside the repository. Put JEV_API__KEY= followed by your key on one line. Replace the /absolute/path/to/judgevet.env placeholder below with its absolute path. Restrict file access to your user. Never commit or share its contents.

Claude Desktop uses a different file: one credential token with an optional trailing newline, without JEV_API__KEY=. Replace its /absolute/path/to/judgevet.key placeholder. judgevet reads this through JEV_API__KEY_FILE. An environment file and a key file have different formats.

For Claude Code, Codex CLI and Pi, start the host from a shell with the key exported. In Bash, read it without echoing or putting it in shell history:

read -r -s -p 'TypeSafe key: ' JEV_API__KEY
printf '\n'
export JEV_API__KEY

On PowerShell, use your approved secret provider to populate the process environment before launching the CLI host. Do not paste a key into a command. Desktop/IDE launches do not necessarily inherit a terminal's environment. Use the file-based GUI recipes instead. Existing literal, file and command sources retain their precedence.

VS Code

Run MCP: Open User Configuration to configure the current user profile, or save this in .vscode/mcp.json for a workspace. MCP: Add Server also provides a guided flow. Merge the entry with existing servers.

{
  "servers": {
    "judgevet": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "judgevet[mcp]==0.10.1", "judgevet-mcp"],
      "envFile": "/absolute/path/to/judgevet.env"
    }
  }
}

Trust the workspace when prompted. Use MCP: List Servers to start the server and review its trust prompt. Open Chat's tool picker and enable judgevet's three tools. Ask the agent to call each tool. Restart the server from its controls after editing configuration; inspect its output if startup fails. If the server still uses old settings, reload the window and start it again. Chat calls require an available model and its account access.

This recipe uses envFile. VS Code also supports password input variables on the extension-host route, but current Agent Host sessions do not receive configurations requiring interactive inputs. Record which route you use. See management and the configuration reference. The root is servers, without an outer mcp object.

Cursor

Save this in .cursor/mcp.json for the project or ~/.cursor/mcp.json for personal use. Merge it with other entries. Project entries take precedence when the same name appears in both locations.

{
  "mcpServers": {
    "judgevet": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "judgevet[mcp]==0.10.1", "judgevet-mcp"],
      "envFile": "/absolute/path/to/judgevet.env"
    }
  }
}

Save and restart Cursor. Inspect Customize > MCPs, enable the server and its tools, then request the three calls below in Agent chat. Check Output > MCP Logs for startup failures. Toggle or re-add the test entry after a fix. Cursor supports ${env:NAME} interpolation, but this file-based route avoids assuming shell inheritance. See the reference and setup guide. Cursor Agent CLI inspection is not evidence that the IDE loaded a server.

Claude Code

After exporting the key, use the native project-scoped add command:

claude mcp add --transport stdio --scope project judgevet --env 'JEV_API__KEY=${JEV_API__KEY}' -- uvx --from 'judgevet[mcp]==0.10.1' judgevet-mcp

Keep judgevet before --env: that option accepts multiple values. The single quotes preserve the variable reference, not the secret value. The equivalent project .mcp.json entry is:

{
  "mcpServers": {
    "judgevet": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "judgevet[mcp]==0.10.1", "judgevet-mcp"],
      "env": {"JEV_API__KEY": "${JEV_API__KEY}"}
    }
  }
}

Use --scope user for personal cross-project setup instead. Inspect with claude mcp get judgevet; claude mcp list checks connection. Start Claude from the credential-bearing shell, approve project configuration, inspect /mcp, and request the three calls. Restart the session after changes. Missing variables can remain literal with a warning: inspect connection status before calling. An account usage limit can block calls after successful MCP discovery. ${VAR} is Claude Code syntax, not Cursor syntax. See Claude Code MCP.

Claude Desktop

This is manual local-server setup, not extension installation. judgevet does not ship a .mcpb bundle or claim a Desktop directory listing. Current Desktop guidance favors extensions with UI-managed sensitive settings; that packaging is deferred. This manual route is documented and mechanically checked, not host-tested.

Open Desktop Settings > Developer > Edit Config. Merge this entry into claude_desktop_config.json. The official manual guide places it at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Use the UI to locate configuration on other supported platforms.

{
  "mcpServers": {
    "judgevet": {
      "command": "uvx",
      "args": ["--from", "judgevet[mcp]==0.10.1", "judgevet-mcp"],
      "env": {"JEV_API__KEY_FILE": "/absolute/path/to/judgevet.key"}
    }
  }
}

Use actual absolute paths for both the executable and key file. On Windows, escape backslashes in JSON or use forward slashes, for example C:/Users/your-name/private/judgevet.key. Do not use shell interpolation. Fully quit Desktop and reopen it. Inspect Connectors for tools and Developer settings for connection status/logs, then request all three calls. Check paths and key-file permissions if it fails. Supported platforms include macOS, Windows and a Linux beta with stated distribution requirements. A browser session does not exercise this local Desktop route.

Configure Codex for a project

Save this in .codex/config.toml in a trusted project, or in ~/.codex/config.toml for user-wide settings. Merge with existing settings.

[mcp_servers.judgevet]
command = "uvx"
args = ["--from", "judgevet[mcp]==0.10.1", "judgevet-mcp"]
env_vars = ["JEV_API__KEY"]

After exporting the key, start Codex CLI from that shell. env_vars forwards the named environment variable without storing its value in TOML. Inspect saved configuration with:

codex mcp get judgevet

This is not live discovery. In the fresh CLI session, use /mcp, confirm the three tools, and request the calls below. Restart the configured client after changes. Accept project trust through Codex before loading project settings. A command-line trust override alone did not load this recipe in CLI 0.156.1. Check trust, executable path and startup diagnostics if tools are absent.

Approve the requested tool calls in the host. Headless execution with approval policy never can discover tools while rejecting every call. For authorized automation, configure approval for the three named tools explicitly; consult tool approval settings. Discovery alone does not establish that a call was approved or completed. See MCP setup and configuration precedence.

Pi CLI access

Pi's official guidance leaves MCP to extensions and supports CLI tools through its Bash tool. This recipe selects the existing CLI, with no MCP extension or discovery claim. Install base judgevet persistently as described in installation, or use the uvx alternative below. Start Pi from the shell where you exported the key. Ask Pi to run these exact commands through its Bash tool:

uvx --from 'judgevet==0.10.1' judgevet 'Two checks passed.' '{"noul_question":{"type":"noul","instructions":"Did the checks pass?"}}' --json

uvx --from 'judgevet==0.10.1' judgevet 'Two checks passed.' '{"choice_question":{"type":"choice","instructions":"Did the checks pass?","criteria":{"yes":"Yes","no":"No"}}}' --json

uvx --from 'judgevet==0.10.1' judgevet 'Two checks passed.' '{"score_question":{"type":"score","instructions":"Did the checks pass?","criteria":["Poor","Fair","Good","Excellent"]}}' --json

Inspect the actual tool execution and JSON answers, model and usage. A model's claim that it ran a command is insufficient. Command-not-found errors require checking Pi's executable path; missing credentials require restarting Pi from the configured shell. An optional Pi skill can point to these commands, but no skill installation is required.

Verify the connection

In each MCP host, discover exactly ask_noul, ask_choice, and ask_score. Send these complete argument objects to the corresponding tools:

ask_noul:

{"state":"Two checks passed.","instruction":"Did the checks pass?"}

ask_choice:

{"state":"Two checks passed.","instruction":"Did the checks pass?","criteria":{"yes":"Yes","no":"No"}}

ask_score:

{"state":"Two checks passed.","instruction":"Did the checks pass?","criteria":["Poor","Fair","Good","Excellent"]}

Tool	Expected structured answer
ask_noul	noul probability between 0 and 1, model, usage
ask_choice	choice, confidence, probabilities, model, usage
ask_score	numeric score, confidence, probabilities, legend, model, usage

Require a successful tool answer, not a tool error. Values vary. This checks integration, not judgment accuracy. See the MCP reference and adapter contract. For failures, use host-specific diagnosis.

The official registry listing is metadata publication. It does not establish availability in VS Code's gallery, Cursor's marketplace or Desktop's directory. Use these manual routes unless a native install link has been separately verified.

Optional: use direnv

If you already use direnv, it can wrap the published launcher. The project must have a reviewed, approved .envrc exporting the key:

direnv exec /absolute/path/to/project uvx --from 'judgevet[mcp]==0.10.1' judgevet-mcp

This is an alternative credential mechanism, not a judgevet prerequisite. direnv exec loads the approved environment without relying on an interactive shell startup file.

Optional: run MCP from a source checkout

For development only, use a checkout and its approved environment:

direnv exec /absolute/path/to/judgevet uv run --directory /absolute/path/to/judgevet --locked --extra mcp judgevet-mcp

You can instead supply credentials explicitly and run uv run --locked --extra mcp judgevet-mcp from the checkout. Consumer host setup uses the published package and needs neither this checkout nor direnv.