ocserv-admin-mcp

ocserv-admin-mcp is a safe administrative package for ocserv.

It is not a bot, chat runtime, or general agent framework. It provides a constrained localhost backend plus an MCP server that expose a small audited tool surface for VPN administration. Any MCP-capable agent can integrate with it, including NanoBot.

What it is

• A localhost-only admin API for approved ocserv operations
• A strict MCP tool surface for agents
• Safety controls for confirmations, allowlists, and rate limits
• Deterministic audit logging, rollback, reload safety, and verification artifacts
• Deployment artifacts for systemd, sudo -n, and VPS installation

What it is not

• Telegram integration
• Chat UX or conversation orchestration
• Free-text intent parsing
• Arbitrary shell access
• A replacement for NanoBot or any other agent runtime

Public tool surface

• list_users
• list_sessions
• list_groups
• show_user_ips
• disconnect_session
• create_user
• update_user_ip
• disable_user
• disable_group_users
• delete_user
• assign_group
• create_group
• delete_group
• reload_service
• rollback_last_change
• confirm_action

validate_config remains an internal backend capability and is not part of the default public MCP tool set.

Supported clients

• NanoBot via deploy/examples/nanobot-config.example.json
• Generic MCP clients via deploy/examples/generic-mcp-client.example.json

Security boundary

• Backend binds to loopback only
• Clients authenticate with a shared bearer token
• Actors must be explicitly allowlisted with OCSERV_ADMIN_ALLOWED_ACTORS
• Privileged operations execute only through sudo -n allowlisted commands
• Destructive actions require explicit confirmation and are audited

Repository layout

• src/ — backend, adapter, safety, audit, and MCP transport layers
• deploy/ — systemd, sudoers, env examples, and client config examples
• docs/ — requirements, development plan, verification plan, knowledge graph
• tests/ — unit and integration coverage for the approved admin surface

Operational guidance

Start with deploy/README.md for host setup, runtime expectations, VPN client-to-client routing/firewall requirements, static per-user IP behavior, and recovery guidance.