Consail MCP
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
# 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 registered only for capabilities on the identity. A hosted or CI process sets CONSAIL_CLIENT_ID (the client UUID) and CONSAIL_CLIENT_SECRET (consailc_). Those are exchanged at POST /oauth/token. Tool calls send the access token, not the secret. The client is bound to one environment, so this process does not send X-Consail-Environment. A user consail_* key is rejected at startup. With no secret, local stdio reads the CLI credential file (the same lock consail login uses) and sends that user access token.
Public hosted origin will be https://mcp.consail.com (Phase B — not implemented in this package yet).
Phase A tools
status and env_list are registered for any live client. The others are registered only when the startup identity includes the capability. Arguments cannot add a dataset, a pipeline, or an environment.
Tool | Needs | Consail API |
| live identity | client: |
| live client |
|
|
|
|
|
|
|
|
|
|
|
|
|
| any grant |
|
|
|
|
|
|
|
|
|
|
|
|
|
ask takes a question and an optional subset of granted dataset ids. It has no SQL argument and no execute mode. Core serves /api/v1/ask to API clients only, so a CLI (user) session does not get ask.
Every tool is annotated readOnlyHint: true, destructiveHint: false, openWorldHint: false.
A dataset or pipeline outside the grants, in another tenant, or that does not exist returns the same 404 "<dataset|pipeline> not found". Core's 403 dataset is not granted to this client from pipeline_validate is reported as that 404 too, so tool errors do not reveal whether a resource exists.
API clients must be integration-mode. Core's operator-mode allowlist refuses GET /api/v1/auth/client, GET /api/v1/environments and GET /api/v1/auth/me, which the startup probe and status need. An operator-mode client exits at startup with an "integration-mode API clients only" error.
Never exposed: raw SQL, query explorer, secret_get, API-client management, deletes, writes. pipeline_run / run_get stay Phase C and need the pipeline_run grant.
Related MCP server: agent-kernel-mcp
Requirements
Node.js 22.12+
A Consail instance (local, staging, or prod API)
An API client id and secret (
consailc_), or a CLI session fromconsail login. Userconsail_*keys are rejected. The secret is exchanged for an access token and is not sent on tool calls.
Install / run locally
git clone https://github.com/consail-labs/consail-mcp.git
cd consail-mcp
npm install
npm run buildEnvironment
Variable | Required | Description |
| yes | Consail API base URL (e.g. |
| with a secret | API client UUID |
| or a CLI session | API client secret. Must start with |
| no | Per-request timeout (default |
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_CLIENT_ID=00000000-0000-0000-0000-000000000000
export CONSAIL_CLIENT_SECRET=consailc_your_secret
npm startnpm 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_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
"CONSAIL_CLIENT_SECRET": "consailc_your_secret"
}
}
}
}Or via npx after publish:
{
"mcpServers": {
"consail": {
"command": "npx",
"args": ["-y", "@consail-labs/consail-mcp"],
"env": {
"CONSAIL_URL": "https://api.consail.dev",
"CONSAIL_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
"CONSAIL_CLIENT_SECRET": "consailc_your_secret"
}
}
}
}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_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
"CONSAIL_CLIENT_SECRET": "consailc_your_secret"
}
}
}
}Restart Claude Desktop after saving.
Security defaults
Auth fail-closed — a missing secret with no CLI session, a
consail_*user key, a secret withoutCONSAIL_CLIENT_ID, or a non-2xx startup probe exits before tools are served. A revoked or expired CLI session reportsCLI session expired or revoked. Run consail login.The client probe isGET /api/v1/auth/client. The user probe isGET /api/v1/auth/me. The access token is re-exchanged or refreshed when it is inside 60 seconds of expiry, and once after a 401. A 403 does not refresh. API 401/403 returns structured errors (no stack dumps).Grant binding — the client is pinned to one environment. Tool arguments cannot name another environment, or a dataset or pipeline outside the grant list. The access token is not sent to routes outside the read allowlist plus
POST /api/v1/ask. A user session skips the grant list; the API enforces that user's access.Preview row cap — default 50, hard max 5000 (enforced in this server before calling Consail).
Ask — registered only with the
askgrant. The body issql_only. There is noexecutemode and no SQL argument.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:secretsGate coverage:
Auth fail-closed (
consail_rejected,consailc_accepted with a client id, startup probe failure exits)Preview row cap (default + hard 5000)
Fixtures contain no secret values
A tool call sends the access token, and routes outside the allowlist are refused before the request
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
Phase | Status |
A stdio read tools + | this package |
B hosted streamable HTTP at | not implemented |
C | not in this slice |
License
Apache-2.0
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Connect AI agents to Replynodes over the Model Context Protocol.
Read a project's prompts, logs and agents, and send new work to the agent on your own machines.
Connect an agent to Sidequest’s hosted job exchange to hire work, find work and settle on Monad.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables an AI agent to run local tools on the user's own machine via stdio, including command execution, workspace file read/write, and system status checks.52MIT
- AlicenseBqualityFmaintenanceEnables IDE and DeepSeek Harness agents to control an agent-kernel instance over stdio, exposing tools for auth, projects, assignments, runs, scheduler nudges, and executor settings.12MIT
- AlicenseNot gradedqualityBmaintenanceEnables compatible agents to call registered local tools and read resources through one stdio server, including harness preparation, knowledge search and document management, memory retention/recall, correction proposals, advisory decisions, tool/skill discovery, and log/source inspection.2Apache 2.0
- AlicenseAqualityCmaintenanceExposes the customer-support tool registry over stdio so Claude Desktop or Claude Code can look up customers and orders, track shipments, search help-center articles, update shipping addresses, issue policy-checked refunds and escalate to a human. It reuses the same pydantic validation, ownership and refund policy, approval gate and audit logging as the HTTP agent, with the customer identity taken from server configuration rather than the model.7MIT