@cogniguard/mcp-server

CogniGuard MCP server + CLI capture for AI coding agents.

Track the cognitive impact of your AI coding sessions with the same backend used by CogniGuard on the web, now exposed through MCP tools and optional CLI capture hooks.

Support Status

• Claude Code: full support
  • MCP tools
  • automatic prompt capture via UserPromptSubmit
• OpenClaw: beta dual-path support
  • MCP tool logging via log_prompt
  • optional hook logging via cogniguard-capture
• Other MCP-compatible agents: MCP tools and manual logging
  • auto-capture is only supported where a runtime can invoke cogniguard-capture with the documented contract

Install / Run

All examples below use the published package directly:

npx --yes --package @cogniguard/mcp-server cogniguard-mcp

You can swap cogniguard-mcp for cogniguard-setup or cogniguard-capture as needed.

Quick Setup

Auth/config only

npx --yes --package @cogniguard/mcp-server cogniguard-setup

This authenticates with CogniGuard, stores credentials in ~/.cogniguard/config.json, verifies the connection, and prints next steps for your agent/runtime.

Claude Code full setup

npx --yes --package @cogniguard/mcp-server cogniguard-setup --claude

This does the generic auth/config flow and also registers:

1. the MCP server in Claude Code
2. a UserPromptSubmit hook for automatic prompt capture

Headless setup

printf '%s' "$COGNIGUARD_PASSWORD" | npx --yes --package @cogniguard/mcp-server cogniguard-setup --email [email protected] --password-stdin --non-interactive

Or provide the password via env:

COGNIGUARD_PASSWORD='...' npx --yes --package @cogniguard/mcp-server cogniguard-setup --email [email protected] --non-interactive

MCP Server Configuration

Use this command in any runtime that supports stdio MCP servers:

npx --yes --package @cogniguard/mcp-server cogniguard-mcp

Example JSON config:

{
  "mcpServers": {
    "cogniguard": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package", "@cogniguard/mcp-server", "cogniguard-mcp"],
      "tools": ["*"]
    }
  }
}

Prompt Logging Paths

CogniGuard supports two ingestion paths that land in the same backend flow.

1. MCP tool path

Call the log_prompt MCP tool once per prompt.

This is the recommended path for OpenClaw and any agent that can already invoke MCP tools reliably.

2. CLI capture path

Use cogniguard-capture when your runtime can invoke a shell command/hook directly.

Argv mode

npx --yes --package @cogniguard/mcp-server cogniguard-capture "Explain this stack trace" --tool openclaw --model claude-opus-4 --session-id abc123 --cwd /workspace/repo

Supported tools:

• claude-code
• cursor
• cline
• copilot
• windsurf
• openclaw
• other

Stdin JSON mode

This is kept for Claude Code hook payloads:

{
  "prompt": { "content": "Explain this stack trace" },
  "model": "claude-sonnet-4-5",
  "session_id": "abc123",
  "cwd": "/workspace/repo"
}

Environment Bootstrap

If ~/.cogniguard/config.json does not exist, the runtime can bootstrap from env vars:

• COGNIGUARD_ACCESS_TOKEN
• COGNIGUARD_REFRESH_TOKEN
• COGNIGUARD_USER_ID

Optional:

• COGNIGUARD_EMAIL
• COGNIGUARD_SUPABASE_URL
• COGNIGUARD_SUPABASE_ANON_KEY
• COGNIGUARD_TOKEN_EXPIRES_AT

When bootstrap env vars are used, CogniGuard immediately writes a real ~/.cogniguard/config.json so token refreshes persist for later short-lived processes like cogniguard-capture.

MCP Tools

| Tool | Description | |------|-------------| | log_prompt | Capture a prompt for cognitive analysis | | get_cognitive_score | Your cognitive health score (0-100) for the last 7 days | | get_session_metrics | Today's prompt count, zone distribution, session duration | | get_coaching_advice | Personalized cognitive coaching based on your patterns |

OpenClaw Notes

OpenClaw is currently supported in two ways:

• Tool path: call cogniguard__log_prompt per prompt
• Hook path: invoke cogniguard-capture from PATH

Recommended hook shape:

execFile(
  "cogniguard-capture",
  [
    content.slice(0, 10000),
    "--tool", "openclaw",
    "--model", event.context.model || "unknown",
    "--session-id", event.context.sessionId || "",
    "--cwd", process.cwd(),
  ],
  {
    timeout: 10000,
    env: { ...process.env, PATH: process.env.PATH },
  },
  (err) => {
    if (err) console.error(`[cogniguard-logger] ${err.message}`);
  }
);

Hooks and MCP tools are separate integration surfaces. The hook should not assume it can call MCP tools internally.

Development

cd packages/mcp-server
npm install
npm run build