monolog-research-mcp

MCP server (stdio transport) that logs VS Code / AI-agent chat sessions to a Monolog research backend.

Each call to logResearchExchange appends a human + agent turn pair to a persistent research session, enabling passive collection of AI coding-assistant interactions for study analysis.

It is tool-agnostic and AI-provider-agnostic: it works with any MCP-capable coding tool (VS Code + Copilot, Claude Code, Cursor, Windsurf, …) and with whatever AI provider that tool is pointed at — OpenAI, Anthropic, Google, a local model, or an aggregator such as OpenRouter. The server only logs your chat turns; it never sees or needs your AI provider key. The single key it uses is your Monolog participant key (mlg_k_…).

Quickstart (turnkey — any tool, any AI provider)

1. Get a participant key. Sign in at monolog.work → Settings → Research and generate a key (mlg_k_…). (No separate auth to set up — the key is the only credential the logger needs.)
2. Add the server to your tool's MCP config (see Installation for the exact file per tool). The simplest, zero-install form:

   {
     "monolog-research": {
       "command": "npx",
       "args": ["-y", "monolog-research-mcp"],
       "env": { "MONOLOG_API_KEY": "mlg_k_your_key_here" }
     }
   }

3. Add one instruction telling the agent to log every turn (see Instruction snippet).
4. Reload / restart your tool. Every turn is now logged in the background with zero added latency.

OpenRouter note: if you run Copilot (or any tool) against OpenRouter, make sure the instruction's trailing acknowledgment line is present (step 3). It prevents a spurious "no response was returned" error that some OpenRouter connectors raise when a tool call is the last action of a turn.

Global setup — log from every project (recommended)

The Quickstart above registers the logger per workspace, which means it only runs when that one project is open. To log every project from every editor window — with no API key stored in any mcp.json — set it up once at the user level:

1. Put your key in your home directory

Create ~/.ai-research-api-key containing just the raw key:

# macOS / Linux / WSL
printf '%s' 'mlg_k_your_key_here' > ~/.ai-research-api-key
chmod 600 ~/.ai-research-api-key

# Windows PowerShell
'mlg_k_your_key_here' | Out-File -NoNewline -Encoding ascii "$env:USERPROFILE\.ai-research-api-key"

The server checks ~/.ai-research-api-key (and ~/.config/monolog/.ai-research-api-key) automatically — see Key resolution order. No env block needed.

2. Register the server at the USER level (not per-workspace)

| Tool | User-level config file | |-----------------|------------------------| | VS Code + Copilot | %APPDATA%\Code\User\mcp.json (Windows) · ~/Library/Application Support/Code/User/mcp.json (macOS) · ~/.config/Code/User/mcp.json (Linux) | | Claude Code | ~/.claude.json | | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

Add (note: no env key — the key comes from the home-dir file):

{
  "servers": {
    "monolog-research": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "monolog-research-mcp"]
    }
  }
}

Some tools use "mcpServers" instead of "servers" as the top-level key — match whatever the tool's other entries use.

3. Add the instruction at the USER level too

Put the instruction snippet somewhere global so it applies to every project — for VS Code that's a *.instructions.md file in your user prompts folder (%APPDATA%\Code\User\prompts\ on Windows), not .github/copilot-instructions.md (which is per-repo).

4. Reload every editor window

That's it — every project now logs automatically, the key lives in exactly one file, and nothing sensitive is committed or stored in mcp.json.

Avoid double-logging: if a project also has a workspace-level monolog-research entry (e.g. an older .vscode/mcp.json), remove it so the server doesn't run twice in that project.

Maintainers: syncing the key from the Ansible vault

In this repo the participant key is stored in the encrypted ansible/secrets.yml vault as ai_research_api_key. The ansible/setup-secrets.yml playbook writes it to both the repo root (.ai-research-api-key) and your home directory (~/.ai-research-api-key) for the global setup above:

cd ansible
ansible-playbook setup-secrets.yml --ask-vault-pass

Requirements

• Node.js ≥ 18
• A Monolog research API key (mlg_k_…) — generate one yourself at monolog.work under Settings → Research, or obtain one from your study coordinator.

Installation

Option A — npx (no install, zero config)

Add to .vscode/mcp.json:

{
  "monolog-research": {
    "command": "npx",
    "args": ["-y", "monolog-research-mcp"],
    "env": {
      "MONOLOG_API_KEY": "mlg_k_your_key_here"
    }
  }
}

Option B — key file (avoid storing key in mcp.json)

Place your raw API key in a file named .ai-research-api-key at your workspace root:

mlg_k_your_key_here

Then omit MONOLOG_API_KEY from the env block:

{
  "monolog-research": {
    "command": "npx",
    "args": ["-y", "monolog-research-mcp"]
  }
}

Option C — global install

npm install -g monolog-research-mcp

{
  "monolog-research": {
    "command": "monolog-research-mcp",
    "env": { "MONOLOG_API_KEY": "mlg_k_your_key_here" }
  }
}

Configuration

All settings are optional except the API key.

| Environment variable | Default | Description | |------------------------|------------------------|--------------------------------------------------| | MONOLOG_API_KEY | (required) | Research API key. Falls back to a key file (see below). | | MONOLOG_KEY_FILE | (unset) | Explicit path to a key file (highest-priority fallback). | | MONOLOG_URL | https://monolog.work | Backend URL (override for self-hosted instances) | | MONOLOG_PARTICIPANT | os.hostname() | Participant identifier for session grouping | | MONOLOG_SOURCE | vscode-copilot-mcp | Source label recorded with each session | | MONOLOG_PROJECT | cwd basename | Project name recorded with each turn |

Key resolution order

If MONOLOG_API_KEY is not set, the server reads the key from the first file that exists:

1. $MONOLOG_KEY_FILE — explicit override
2. <cwd>/.ai-research-api-key — per-workspace
3. <package>/../../.ai-research-api-key — repo root (when run from source)
4. ~/.ai-research-api-key — global; works in every project & editor window
5. ~/.config/monolog/.ai-research-api-key — global, XDG-style

Recommended global setup: put your key in ~/.ai-research-api-key and register the server once at the user level (not per-workspace) with no env key block. Every project then logs automatically with no secret stored in any mcp.json. See Global setup below.

Exposed MCP tool

logResearchExchange

Appends a human + agent turn pair to the active research session.

{
  "name": "logResearchExchange",
  "arguments": {
    "user": "The user's prompt, verbatim.",
    "assistant": "The assistant's full response, verbatim."
  }
}

Returns a minimal non-empty result { content: [{ type: "text", text: "logged" }] } on success. The response is fire-and-forget — the tool returns immediately and the HTTP write happens in the background so it never adds latency to the agent loop. The non-empty content array is deliberate: an empty array causes the OpenRouter connector in VS Code Copilot to report "Sorry, no response was returned." when this tool is the last call in a turn. Agent instructions additionally require a short trailing acknowledgment after the call so the log tool is never the terminal token-producing action.

Secret redaction: Before any data leaves the process, the server scrubs known secret patterns (API keys, tokens, passwords, bearer headers, connection strings) and replaces them with [REDACTED].

Instruction snippet (any tool)

To make your AI assistant call logResearchExchange automatically after every response, add this to its instruction file. The text is identical across tools — only the file location differs:

• VS Code + Copilot: a *.instructions.md file in your user prompts folder, or .github/copilot-instructions.md in the project.
• Claude Code: CLAUDE.md (project root) or ~/.claude/CLAUDE.md (global).
• Cursor: .cursor/rules/monolog-research.mdc (project) or Settings → Rules (global).
• Windsurf: .windsurfrules (project root) or Settings → Cascade → Global Rules.

---
applyTo: "**/*"
---

At the end of **every** response, call the `logResearchExchange` tool exactly once with:
- `user` — the user's most recent prompt, verbatim
- `assistant` — your full response, verbatim

After the call, emit this exact italic line as the final line of the response:

_Logged at [monolog.work](https://monolog.work/research.html#researchers)_

This keeps the log call from being the terminal action, which avoids a spurious
"no response was returned" error on some connectors (e.g. OpenRouter inside Copilot).

Privacy & security

• No data is sent until the first logResearchExchange call — session creation is lazy.
• The server never logs to stdout (only stderr for diagnostics).
• Secret redaction runs unconditionally on every turn before the HTTP request is made.
• Participant keys are scoped server-side to a single study; a leaked key cannot access other studies' data.

License

MIT