Agents / MCP

Meriadoc is designed from the ground up to work with AI coding agents. It exposes tasks as MCP tools, enforces risk controls, and logs every agent action — giving you a secure, audited execution boundary for AI.

MCP server (stdio)

Start the MCP server:

meriadoc serve

This starts a JSON-RPC server over stdio that implements the Model Context Protocol. Agents can:

• Discover tasks with tools/list
• Execute tasks with tools/call
• Receive structured output including success/failure status

Claude Desktop integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "meriadoc": {
      "command": "/usr/local/bin/meriadoc",
      "args": ["serve"]
    }
  }
}

Once configured, Claude can see and call all your Meriadoc tasks as tools.

HTTP API

The HTTP server (meriadoc server) also provides a REST API:

Example — run a task:

curl -X POST http://localhost:8420/api/tasks/myproject:build/run \
  -H "Content-Type: application/json" \
  -d '{"env": [["DEBUG", "true"]], "dry_run": false}'

Risk annotations

Control how agents interact with each task using the agent: block:

tasks:
  status:
    description: "Show current deployment status"
    agent:
      risk_level: low          # auto-approved
    cmds:
      - kubectl get pods

  restart:
    description: "Restart the app"
    agent:
      risk_level: medium       # auto-approved, audited
      requires_approval: false
    cmds:
      - kubectl rollout restart deployment/myapp

  deploy-prod:
    description: "Deploy to production"
    agent:
      risk_level: critical
      requires_approval: true
      confirmation: "This will deploy to production and affect real users. Continue?"
    cmds:
      - ./deploy.sh prod

  internal:
    description: "Not shown to agents"
    agent:
      enabled: false           # hidden from MCP tool list
    cmds:
      - ./internal-only.sh

Risk levels

Every blocked attempt is logged — not just successful runs.

Typed parameters for agents

When an agent calls tools/list, it receives the full env var schema:

{
  "env_vars": [
    {
      "name": "ENVIRONMENT",
      "type": "choice",
      "required": true,
      "default": "dev",
      "options": ["dev", "staging", "prod"]
    },
    {
      "name": "API_KEY",
      "type": "secret",
      "required": true,
      "default": null,
      "options": []
    }
  ]
}

This lets agents validate values before calling, generate UI prompts, and understand which parameters are secrets (never logged).

Audit trail

Enable audit logging in your config to get a record of every agent action:

audit:
  enabled: true
  sinks:
    - type: file
      path: ~/.config/meriadoc/audit.log

Each log entry identifies the caller (mcp-stdio, mcp-http, api, cli), the task, risk level, outcome, and duration. Secret values are never logged. See Audit Logging.

Why Meriadoc for agents?

Traditional task runners expose everything with no guardrails. Meriadoc gives agents a capability-based interface: they can only call predefined tasks, with explicit contracts, and human oversight for risky operations.