@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).

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)

Example MCP client entry:

{
  "mcpServers": {
    "gently": {
      "command": "npx",
      "args": ["-y", "@gently/mcp-server"],
      "env": {
        "GENTLY_API_URL": "<your-graph-api>/v1",
        "GENTLY_IDENTITY_URL": "<your-identity-url>"
      }
    }
  }
}

Project init

Writes gently agent guidance into the current repo:

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

SCIP upload (ADR-0024)

Enrich the graph with a simplified SCIP JSON index (not full protobuf). Requires a token with graph:write (device-flow approver or GENTLY_TOKEN).

When to upload — on CI after scip-typescript / scip-python (or when an operator explicitly asks). Not on every agent query: read tools (gently_query / gently_path / gently_impact) never upload.

MCP tool — gently_upload_scip with path to a JSON file or inline index (opt-in; agents must not call it unless asked).

CLI (preferred for CI):

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

Typical CI: scip-typescript index → convert to the ADR-0024 JSON shape → upload. Bodies over 1 MiB are rejected by the edge.

License

MIT