agentlock-mcp-server

MCP (Model Context Protocol) server that lets Claude Desktop, Cursor, and other MCP-compatible clients call AgentLock as a tool provider. The agent submits actions, polls results, drives browser sessions, and exchanges messages with the user — all through AgentLock's approval + policy engine.

Install

npm install -g agentlock-mcp-server
# or run ad-hoc:
npx agentlock-mcp-server

Authentication

Two modes are supported. Secrets must come from environment variables — CLI flags like --token, --key, --agent-id are hard-rejected because argv is world-readable on Unix via ps aux and /proc/<pid>/cmdline.

1. API Token (recommended)

Create a bearer token in the AgentLock dashboard under the agent's detail page, then:

AGENTLOCK_TOKEN=<token> agentlock-mcp

2. Ed25519 Signing (advanced)

For stricter environments where you want cryptographic request signing:

AGENT_ID=<uuid> \
AGENT_PRIVATE_KEY=<base64> \
agentlock-mcp

The agent's public key must already be registered in the dashboard. The private key stays on the client — the server only ever sees signatures.

Configuration options

| Var | Default | Description | |---|---|---| | AGENTLOCK_URL | https://app.agentlock.net | Base URL of the AgentLock gateway. Override for self-hosted. | | AGENTLOCK_TOKEN | — | Bearer token (auth mode 1). | | AGENT_ID | — | Agent UUID (auth mode 2). | | AGENT_PRIVATE_KEY | — | base64-encoded Ed25519 private key (auth mode 2). |

--url <url> is the only accepted CLI flag. All others exit with a migration message pointing at the env var.

Exposed tools

| Tool | Purpose | |---|---| | request_action | Submit a generic action (HTTP, MCP, any connector). Use for every external call by default. | | get_result | Poll for the result of a previously submitted request. | | browser_open | Start a browser session. Requires human approval. Returns session_id + a11y snapshot. | | browser_action | Drive an open browser session (click, type, navigate, snapshot). No extra approval inside the session. | | browser_login | Fill a login form from a stored credential. The agent never sees the password or TOTP code. | | list_credentials | List available credentials by name/type. Secret values are never returned. | | get_messages | Fetch messages from the user — replies on approvals, or direct DMs from the dashboard. | | send_message | Reply in an existing thread. | | start_thread | Proactively start a new thread to ask the user something. |

Claude Desktop setup

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "agentlock": {
      "command": "npx",
      "args": ["-y", "agentlock-mcp-server"],
      "env": {
        "AGENTLOCK_TOKEN": "<your-token>"
      }
    }
  }
}

Restart Claude Desktop. The request_action / browser_open / ... tools should appear in the tool picker.

Cursor setup

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "agentlock": {
      "command": "npx",
      "args": ["-y", "agentlock-mcp-server"],
      "env": {
        "AGENTLOCK_TOKEN": "<your-token>"
      }
    }
  }
}

Transport

Communicates over stdio. There is no HTTP listener — the MCP client is expected to spawn the binary and pipe JSON-RPC over stdin/stdout per the MCP spec. Logs go to stderr and are passed through to the MCP client's log stream.

Build from source

pnpm install
cd packages/mcp-server
pnpm build
node dist/index.js