Skip to content
MCP server

mcp-agent-template

MCP server template adding role, allowlist and human-confirmation guardrails

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted, Linux
Runs
Locally
Version
0.2.0
Listing updated
today

Similar MCP servers

About mcp-agent-template

mcp-agent-template is an open-source MCP server for security. It runs locally on your machine and is started by your AI client.

The README presents this as a template for building MCP servers that an IT department can let an LLM agent use safely. Every tool call is checked against an allowlist policy file, a caller role (read-only, operator or admin) derived from MCP tool annotations, and per-parameter allowed values before it runs.

Destructive actions require explicit human approval through MCP elicitation. Anything other than a clear yes is treated as a refusal, and refusals are returned to the agent as readable errors rather than fake successes. Each call is written to a JSONL audit log with a correlation id linking the decision, confirmation and result, and secret-like parameters are masked.

The package ships two runnable examples, one enterprise-style with fictitious tickets, directory and inventory data, and one generic ops example for systemd and docker. It is local-first and self-hosted, and the README says it has no cloud service or telemetry. It is dual licensed under AGPL-3.0 with a commercial licence available for companies.

Install

Run in a terminal

claude mcp add mcp-agent-template -- uvx mcp-agent-template

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-agent-template": {
      "command": "uvx",
      "args": [
        "mcp-agent-template"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent-template": {
      "command": "uvx",
      "args": [
        "mcp-agent-template"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "mcp-agent-template": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-agent-template"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent-template": {
      "command": "uvx",
      "args": [
        "mcp-agent-template"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "mcp-agent-template": {
      "command": "uvx",
      "args": [
        "mcp-agent-template"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • MCP_AGENT_TEMPLATE_ROLECaller role: lecteur (read-only), operateur, admin. Defaults to lecteur.
  • MCP_AGENT_TEMPLATE_CONFIRMelicit: the server asks the human; client: the client confirms itself from destructiveHint.
  • MCP_AGENT_TEMPLATE_AUDIT_DIRDirectory of the JSONL audit log.

What it does

Allowlist policy enforcement
Tools absent from the policy file are refused by default.
Role-based tool access
Caller roles map to tool types, with read-only, operator and admin levels.
Human confirmation for destructive tools
Destructive calls use MCP elicitation so a person approves before execution.
JSONL audit logging
Calls are logged with correlation ids and secret-like parameters masked.
Per-parameter value limits
Policy can restrict which values a given tool parameter may take.
Runnable example servers
Enterprise and ops examples run on fictitious local data for testing.

Good for

  • Expose internal ticketing or inventory data to an AI agent with read-only defaults
  • Require a human sign-off before an agent restarts services or deletes records
  • Build an auditable MCP server for an on-premise IT environment
  • Prototype guarded tool access before connecting a real directory or database

Pricing

Open source

AGPL-3.0; commercial licence required for companies

mcp-agent-template FAQ

What does the default role allow?

The default role is lecteur, which is read-only, set through the MCP_AGENT_TEMPLATE_ROLE variable.

How is the human confirmation handled?

With MCP_AGENT_TEMPLATE_CONFIRM set to elicit, the server asks the human through the client; with client, the client confirms itself using the destructiveHint annotation.

Where is the audit log written?

To the directory set by MCP_AGENT_TEMPLATE_AUDIT_DIR, defaulting to ~/.local/state/mcp-agent-template, as a file with 0600 permissions.

Is it free to use?

It is licensed under AGPL-3.0, which the README says is free for individuals, associations and education or research; companies need a commercial licence.

Is mcp-agent-template free?

Yes. mcp-agent-template is open source, so you can use and self-host it for free.

How do I add mcp-agent-template to Claude Code?

Run this command in your terminal: claude mcp add mcp-agent-template -- uvx mcp-agent-template

What are the best alternatives to mcp-agent-template?

The closest alternatives to mcp-agent-template are mcpcut, mcp-gatehouse, Linux MCP daemon (mcpd), MCP Zero-Trust Gateway and KillerSkills.

Where this comes from

  • Description: written from the project's README and its MCP Registry entry.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers