---
title: @envlock/mcp Server
description: MCP server reference for @envlock/mcp — expose environment schema tools to AI coding agents.
url: https://pr-1-7cfcfe393d12.thally.app/envlock-mcp-server
---

# @envlock/mcp Server

MCP server reference for @envlock/mcp — expose environment schema tools to AI coding agents.

MCP server reference for `@envlock/mcp` v0.1.0. Binary: `envlock-mcp`
(stdio transport).

## Setup

Add the server to your MCP client configuration:

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

---

## Tools

All tools are annotated with `readOnlyHint: true` and `idempotentHint: true`.

### envlock_check

Validate environment against a schema.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaPath` | `string` | yes | Path to schema config file |
| `envFilePath` | `string` | no | Path to `.env` file |
| `strict` | `boolean` | no | Report unknown variables |

Returns `{ ok, issues, source }`.

### envlock_inspect

Describe all variables in a schema.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaPath` | `string` | yes | Path to schema config file |

Returns `{ schemaPath, variables }` where `variables` is an array of
`SchemaDescription` objects.

### envlock_render_example

Render `.env.example` text from a schema.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaPath` | `string` | yes | Path to schema config file |

Returns the rendered `.env.example` text.

### envlock_diff

Show differences between a schema and an env file.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaPath` | `string` | yes | Path to schema config file |
| `envFilePath` | `string` | yes | Path to `.env` file |

Returns `{ ok, missing, unknown, invalid, source }`.

### envlock_explain_issue

Get a human-readable explanation and remediation steps for an issue.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | yes | Issue code: `"missing"`, `"invalid"`, or `"unknown"` |
| `key` | `string` | yes | The environment variable name |
| `message` | `string` | no | The original issue message |

Returns `{ code, key, summary, steps }` with a summary and three remediation
steps.

---

## Resource template

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

Returns `describeSchema()` JSON with content type `application/json`.

There is no list callback. The template is discoverable via
`resources/templates/list`.

---

## Path security

The `resolveInsideCwd` function rejects any path that would escape the
server's working directory. All tool and resource handlers use this check
before accessing the filesystem.

## Error handling

Loader failures (config not found, import errors, missing schema export)
return `isError: true` results rather than raising MCP protocol errors.

---

## Programmatic API

### createEnvlockServer

```ts
function createEnvlockServer(
  options?: EnvlockServerOptions,
): McpServer;
```

Creates and returns an MCP server with all five tools and the resource
template registered.

### EnvlockServerOptions

```ts
interface EnvlockServerOptions {
  readonly cwd?: string;
}
```

Defaults to `process.cwd()`.

### SERVER_INFO

```ts
const SERVER_INFO: {
  name: "envlock";
  version: "0.1.0";
};
```

### TOOL_NAMES

```ts
const TOOL_NAMES: {
  check: "envlock_check";
  inspect: "envlock_inspect";
  renderExample: "envlock_render_example";
  diff: "envlock_diff";
  explainIssue: "envlock_explain_issue";
};
```

### SCHEMA_RESOURCE_TEMPLATE

```ts
const SCHEMA_RESOURCE_TEMPLATE: "envlock://schema/{schemaPath}";
```

### resolveInsideCwd

```ts
function resolveInsideCwd(
  cwd: string,
  filePath: string,
): PathResolution;
```

Returns `{ path: string }` on success or `{ error: string }` if the resolved
path escapes `cwd`.

### loadSchemaFile

```ts
function loadSchemaFile(
  schemaPath: string,
  cwd?: string,
): Promise<SchemaLoadResult>;
```

### loadEnvFile

```ts
function loadEnvFile(
  envFilePath: string,
  cwd?: string,
): Promise<EnvFileLoadResult>;
```

### explainIssue

```ts
function explainIssue(input: {
  code: string;
  key: string;
  message?: string;
}): IssueExplanation;
```

Pure, synchronous function. Returns a summary string and three remediation
steps.

---

## Programmatic usage example

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

const server = createEnvlockServer({ cwd: "/path/to/project" });
await server.connect(new StdioServerTransport());
```