@gently/mcp-server

@gently/mcp-server

MCP server for gently. Agents query the knowledge graph over stdio; authorization uses gently's device flow (approve in the console — no tokens in your MCP config).

Local or hosted?

This package is the local server, and it is the one to use when you want gently to see your working copy: it reads the checkout's git remote and can sync your SCIP index.

If you only need graph reads, your deployment also serves a hosted MCP endpoint at https://<your-edge>/mcp that needs no install. Point your host at that URL and it will walk the OAuth flow by itself; it offers the four read tools (gently_query, gently_impact, gently_path, gently_diff).

Install

Cursor — Add the hosted endpoint or add the local server. Both are the same mcp.json entry, base64'd into a deeplink. (Staging today; production URLs replace these once api.gently.is is up.)

Claude — Settings → Connectors → Add custom connector → https://api.stage.gently.is/mcp.

VS Code

code --add-mcp '{"name":"gently","type":"http","url":"https://api.stage.gently.is/mcp"}'

Anything else, or a self-hosted deployment — see Project init, which writes each host's own config format for you.

Run

npx -y @gently/mcp-server

Auth

On the first tool call without credentials, the server returns a console URL and a short code. Approve there, then retry the same tool call so gently can finish signing in. Credentials stay on the machine (owner-only) and refresh automatically. A pending device code is kept across process restarts so a short-lived npx probe does not mint a new code after you already approved.

For CI, set GENTLY_TOKEN to a bearer token instead of using the device flow.

Configure

Point the server at your gently deployment:

Variable	Required	Purpose
GENTLY_API_URL	yes	Graph API base URL (include /v1)
GENTLY_IDENTITY_URL	yes	Identity base URL used for device auth
GENTLY_GRAPH	no	Graph id (defaults to the deployment default)
GENTLY_CLIENT_NAME	no	Label shown on the approval screen
GENTLY_TOKEN	no	Bearer token; skips device flow (CI)

Supported hosts

Every host stores the same wiring in a different place, format, and root key. gently-mcp-init knows all of it, so you never hand-write a config:

Host	Config (default scope)	Format	Guidance file
Cursor	.cursor/mcp.json	JSON mcpServers	.cursor/rules/gently.mdc
Claude Code	.mcp.json	JSON mcpServers	CLAUDE.md
Claude Desktop	claude_desktop_config.json (OS app dir)	JSON mcpServers	— (no repository context)
Codex	~/.codex/config.toml ($CODEX_HOME)	TOML mcp_servers	AGENTS.md
VS Code	.vscode/mcp.json	JSON servers	.github/copilot-instructions.md

Project init

Wires this repository for the hosts it detects, and writes the same agent guidance into whichever file each host actually reads:

npx -y -p @gently/mcp-server gently-mcp-init

# or choose explicitly
npx -y -p @gently/mcp-server gently-mcp-init --client cursor,codex
npx -y -p @gently/mcp-server gently-mcp-init --client claude-desktop --scope user
npx -y -p @gently/mcp-server gently-mcp-init --dry-run
npx -y -p @gently/mcp-server gently-mcp-init --print vscode   # snippet only, writes nothing

Re-running is safe. gently merges its own entry and leaves your other MCP servers, comments, and settings untouched — including in ~/.codex/config.toml, where only the [mcp_servers.gently] block is rewritten. A file gently does not own (a hand-written rules file, an unparseable config) is reported for you to merge, never overwritten.

The generated config contains no token: the server authorizes itself through the device flow. Automation that cannot approve a device flow can pass one explicitly with --env GENTLY_TOKEN=….

Driving a host headlessly

gently-mcp-harness runs a real host against a prompt corpus, so gently is exercised the way an editor exercises it — the host loads its own config, spawns this server over stdio, and picks its own tools. Cursor, Claude Code, and Codex ship headless CLIs; Claude Desktop and VS Code are GUI-only and can be configured but not driven.

gently-mcp-harness --client codex --suite-file suites.json --suite hard --log-dir ./logs
gently-mcp-harness --list

SCIP sync (ADR-0010)

Enrich the graph with a simplified SCIP JSON index (not full protobuf). Uploads are per JWT sub: each developer keeps a separate head on the same branch. Requires graph:write (and graph:read for head checks).

When to sync — MCP boot auto-checks when GENTLY_SCIP_AUTO is unset/1 (set 0 to disable). Agents should prefer gently_scip_sync over force upload. Read tools (gently_query / gently_path / gently_impact) never upload.

Index path — GENTLY_SCIP_PATH or .gently/index.scip.json. Optional GENTLY_SCIP_CMD regenerates the index before upload when stale.

MCP tools

• gently_scip_sync — upload only if local content hash ≠ this identity's server head
• gently_upload_scip — force upload (path or inline index)

CLI:

# Change-detected (preferred)
npx -y -p @gently/mcp-server gently-mcp-scip-upload --sync --source github:org/repo

# Force upload
npx -y -p @gently/mcp-server gently-mcp-scip-upload \
  --file ./index.scip.json \
  --source github:org/repo

Bodies over 1 MiB are rejected by the edge.

License

MIT