---
title: @envlock/mcp
description: MCP server that exposes Envlock schema validation, inspection, and diffing to coding agents and AI tools.
url: https://pr-1-ee19382a0710.thally.app/envlock/mcp
---

# @envlock/mcp

MCP server that exposes Envlock schema validation, inspection, and diffing to coding agents and AI tools.

## Setup

Add the Envlock MCP server to your editor or agent configuration. The server runs over stdio.

**Claude Code or Cursor** -- add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "envlock": {
      "command": "npx",
      "args": ["-y", "@envlock/mcp"]
    }
  }
}
```

**Claude Desktop** -- add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "envlock": {
      "command": "npx",
      "args": ["-y", "@envlock/mcp"]
    }
  }
}
```

If `@envlock/mcp` is already installed as a devDependency, you can use the binary name directly:

```json
{
  "mcpServers": {
    "envlock": {
      "command": "npx",
      "args": ["envlock-mcp"]
    }
  }
}
```

## Server info

| Field | Value |
|-------|-------|
| Name | `envlock` |
| Version | `0.1.0` |

The server provides instructions to connected clients: "Envlock validates environment variables against a typed contract (envlock.config.mjs). Use envlock_inspect to learn what an app needs, envlock_check to validate a .env file, and envlock_render_example to produce .env.example text."

## Tools

All tools are annotated as **read-only** and **idempotent**. They never modify files or environment state.

### `envlock_check`

Validates environment variables against the schema. Without `envFilePath`, validates the server's own `process.env`.

**Input**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `schemaPath` | string | yes | Path to the envlock config file, relative to the server working directory. |
| `envFilePath` | string | no | Path to a dotenv file to validate. When omitted, `process.env` is used. |
| `strict` | boolean | no | Report undeclared variables. Only applies when `envFilePath` is provided. |

**Output** -- structured content with `ok` (boolean), `issues` (array of issue objects), and `source` (string describing what was validated).

### `envlock_inspect`

Returns a description of every variable declared in the schema.

**Input**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `schemaPath` | string | yes | Path to the envlock config file. |

**Output** -- structured content with `schemaPath` and `variables` (array of variable descriptions including type, required, default, secret, description, and constraints).

### `envlock_render_example`

Renders `.env.example` text from the schema.

**Input**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `schemaPath` | string | yes | Path to the envlock config file. |

**Output** -- a text content block containing the rendered `.env.example` file content, ready to write to disk.

### `envlock_diff`

Performs a strict diff of a dotenv file against the schema. Reports missing, unknown, and invalid variables.

**Input**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `schemaPath` | string | yes | Path to the envlock config file. |
| `envFilePath` | string | yes | Path to the dotenv file to diff. |

**Output** -- structured content with `ok` (boolean), `missing` (array of key names), `unknown` (array of key names), `invalid` (array of issue objects), and `source` (string).

### `envlock_explain_issue`

Explains a validation issue and suggests remediation steps. This is a **pure function** that requires no file access.

**Input**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | `"missing"` or `"invalid"` or `"unknown"` | yes | The issue code to explain. |
| `key` | string | yes | The environment variable name involved. |
| `message` | string | no | The original issue message, for additional context. |

**Output** -- structured content with `code`, `key`, `summary`, and `steps` (array of remediation steps).

The explanations returned for each code:

- **missing** -- the variable is required by the contract but the environment does not provide a non-empty value. Steps: set the variable, mark it as `.optional()` or `.default()` in the schema, or run `envlock example` to generate a template.
- **invalid** -- the variable is set but its value does not satisfy the declared type. Steps: correct the value, adjust the builder in the schema, or re-run `envlock check`.
- **unknown** -- the variable exists in the env file but the contract does not declare it. Steps: declare it in the schema, remove it from the file, or note that strict mode controls this reporting.

## Resource template

The server exposes a resource template for reading schema descriptions:

```
envlock://schema/{schemaPath}
```

The `schemaPath` parameter should be URL-encoded. The resource returns the output of `describeSchema()` as JSON with MIME type `application/json`.

This resource is discoverable via the MCP `resources/templates/list` method. There is no static resource list.

## Path confinement

All file paths provided to tools and resources must resolve inside the server's working directory. If a path resolves outside the working directory (for example, using `..` traversal or an absolute path pointing elsewhere), the server returns an error:

`path "<filePath>" is outside the server working directory (<base>); start envlock-mcp from the project root`

## Programmatic embedding

You can create and connect the server programmatically:

```ts
import { createEnvlockServer } from "@envlock/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createEnvlockServer({ cwd: process.cwd() });
await server.connect(new StdioServerTransport());
```

The `createEnvlockServer` function accepts an optional `EnvlockServerOptions` object:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `cwd` | string | `process.cwd()` | The working directory used for path resolution and confinement. |

## Exported types and constants

| Export | Description |
|--------|-------------|
| `createEnvlockServer` | Factory function that returns a configured MCP server instance. |
| `SERVER_INFO` | Object with `name` (`"envlock"`) and `version` (`"0.1.0"`). |
| `TOOL_NAMES` | Object mapping logical names to tool identifiers: `check`, `inspect`, `renderExample`, `diff`, `explainIssue`. |
| `SCHEMA_RESOURCE_TEMPLATE` | The URI template string `"envlock://schema/{schemaPath}"`. |
| `EnvlockServerOptions` | Options type for `createEnvlockServer`. |
| `explainIssue` | The pure function behind the `envlock_explain_issue` tool. |
| `ExplainIssueInput` | Input type for `explainIssue`. |
| `IssueExplanation` | Return type of `explainIssue`. |
| `resolveInsideCwd` | Path confinement utility. Returns the resolved path or an error. |
| `loadSchemaFile` | Loads and validates a schema from a file path within the working directory. |
| `loadEnvFile` | Reads and parses a dotenv file within the working directory. |
| `PathResolution` | Result type from `resolveInsideCwd`. |
| `SchemaLoadResult` | Result type from `loadSchemaFile`. |
| `EnvFileLoadResult` | Result type from `loadEnvFile`. |