Consail MCP

# Consail MCP

Governed Model Context Protocol server for Consail.

Agents connect to Consail. They never get the database password.

Phase A ships a local stdio server for Cursor and Claude Desktop. Tools are a fixed allowlist mapped 1:1 to existing Consail HTTP APIs. Auth is your existing consail_* API key plus environment binding (X-Consail-Environment).

Public hosted origin will be https://mcp.consail.com (Phase B — not implemented in this package yet).

Phase A tools (read / validate only)

Never exposed (Phase A): raw SQL, secret_get, API-key create/delete, deletes, writes, pipeline_run / run_get (Phase C).

Related MCP server: agent-kernel-mcp

Requirements

• Node.js 20+

• A Consail instance (local, staging, or prod API)

• A consail_* API key scoped to the environment you intend to use

Install / run locally

git clone https://github.com/consail-labs/consail-mcp.git
cd consail-mcp
npm install
npm run build

Environment

Copy .env.example if useful — the MCP host should inject env vars into the server process (do not commit real keys).

export CONSAIL_URL=http://localhost:8080
export CONSAIL_API_KEY=consail_your_key
export CONSAIL_ENVIRONMENT=dev
npm start

npm start speaks MCP over stdio (stdout is the protocol channel; logs go to stderr).

Cursor config

Add to Cursor MCP settings (JSON), pointing at the built entrypoint:

{
  "mcpServers": {
    "consail": {
      "command": "node",
      "args": ["/absolute/path/to/consail-mcp/dist/index.js"],
      "env": {
        "CONSAIL_URL": "http://localhost:8080",
        "CONSAIL_API_KEY": "consail_your_key",
        "CONSAIL_ENVIRONMENT": "dev"
      }
    }
  }
}

Or via npx after publish:

{
  "mcpServers": {
    "consail": {
      "command": "npx",
      "args": ["-y", "@consail-labs/consail-mcp"],
      "env": {
        "CONSAIL_URL": "https://api.consail.dev",
        "CONSAIL_API_KEY": "consail_your_key",
        "CONSAIL_ENVIRONMENT": "dev"
      }
    }
  }
}

Claude Desktop config

Edit Claude Desktop config (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "consail": {
      "command": "node",
      "args": ["C:\\\\absolute\\\\path\\\\to\\\\consail-mcp\\\\dist\\\\index.js"],
      "env": {
        "CONSAIL_URL": "http://localhost:8080",
        "CONSAIL_API_KEY": "consail_your_key",
        "CONSAIL_ENVIRONMENT": "dev"
      }
    }
  }
}

Restart Claude Desktop after saving.

Security defaults

• Auth fail-closed — missing/invalid consail_* key: process refuses to start; API 401/403 returns structured errors (no stack dumps).

• Tenant / env binding — data tools always send X-Consail-Environment from CONSAIL_ENVIRONMENT. Tool arguments cannot override the bound environment.

• Preview row cap — default 50, hard max 5000 (enforced in this server before calling Consail).

• No secrets in payloads — tools never call secret APIs; fixtures are grepped in CI (npm run check:secrets).

Tests (security gate A)

npm test
npm run check:secrets

Gate coverage:

1. Auth fail-closed (config + 401)

2. Preview row cap (default + hard 5000)

3. Fixtures contain no secret values

4. Env isolation: key/session for env A cannot preview as env B

Stack

• TypeScript + official @modelcontextprotocol/server (MCP SDK v2)

• Thin HTTP client → Consail REST (same shapes as consail-cli --json)

Why TypeScript: official MCP SDK, natural fit for Cursor/Claude Desktop stdio packaging (node / npx), while staying a separate thin repo (not in Atlas Core).

Roadmap

License

Apache-2.0