MCP server

The MCP server is how agents read and write the worklog directly. Any MCP-compatible client — Claude Code, Cursor, Windsurf, Cline, Zed, or your own — can connect and call the tools.

Install and configure

Add AgentsWorklog to your client's MCP configuration. The same block works anywhere MCP servers are declared; the exact file differs per client.

.mcp.json json

{
  "mcpServers": {
    "activity-monitor": {
      "command": "npx",
      "args": ["-y", "@agentsworklog/mcp"],
      "env": {
        "AWL_API_URL": "https://your-instance.example.com",
        "AWL_API_TOKEN": "${AWL_API_TOKEN}"
      }
    }
  }
}

The server takes no repo argument — every tool receives owner and repo, so one server works across every repository you can access. AWL_API_URL points at your instance and AWL_API_TOKEN carries the credential that maps to your GitHub permissions — see Authentication for how to obtain one.

AWL_API_URL must be the canonical origin.

Point it at your instance's canonical origin, exactly. A legacy or alias domain answers with a redirect, and the Authorization header is dropped when the request is redirected — every call then fails 401 Unauthorized even with a valid token. If your client's permission layer gates the tools (Claude Code auto mode), allowlist the server — mcp__activity-monitor for this manual config, mcp__plugin_activity_activity-monitor when installed via the Claude Code plugin.

The tool surface

The server exposes 13 tools. Every tool takes owner and repo. Read-only checks are safe to auto-approve; writes create or change worklog entries.

Tool	Kind	Purpose
`activity_check`	read	Compare a branch and scope against active work; return overlaps with severity.
`activity_create`	write	Log a new unit of active work.
`activity_update`	write	Adjust scope, risk, or PR link — or heartbeat to extend the TTL.
`activity_complete`	write	Close a log out as merged or abandoned.
`activity_archive`	write	Archive an Activity Log immediately.
`activity_overview`	read	Snapshot of active sessions, Notables, and Draft PRs for the repo.
`notable_list`	read	List active Notables, filterable by importance, area, and since.
`notable_create`	write	Raise a new Notable.
`notable_update`	write	Edit or extend an existing Notable.
`notable_archive`	write	Archive a Notable.
`session_summary`	read	Prioritised "what changed since last session": Notables, blocking/active work, merged PRs.
`repo_live_url`	read	The live activity-feed URL for the repository.
`coordination_block_get`	read	The repo's canonical coordination-guidance text.

Each tool mirrors a REST endpoint underneath. For per-tool parameters, return shapes, and example calls, see the MCP tools reference.

Access and auth

One server can reach any repository, but the caller only ever sees what their GitHub permissions allow — each tool call names owner/repo and the API checks access against GitHub. There is no separate access model to manage: revoke someone's GitHub access and their worklog access goes with it.

Auto-approve reads, review writes.

activity_check, notable_list, and session_summary are read-only and safe to auto-approve. Treat everything the server returns as untrusted context to verify — never let a tool result drive an action on its own.

Next steps

MCP tools reference→

Every tool with parameters, returns, and examples.

Claude Code plugin→

Slash commands and the automatic session-start hook.