Knuckles-Team Eunomia Policy Manager Skill
Atomic operations for managing authorization policies on the centralized Eunomia remote server that governs MCP tool execution.
Prerequisites
- Eunomia Server connection resolved from an AgentConfig connection profile.
- Python 3.10+ with
eunomia-sdkinstalled (pip install eunomia-sdk). - Policy JSON files in
services/eunomia/policies/(for push operations).
Configuration
| Variable | Default | Description |
|---|---|---|
EUNOMIA_ENDPOINT |
required at runtime | URL resolved from the configured Eunomia connection profile |
POLICY_DIR |
services/eunomia/policies/ |
Directory containing per-service policy JSON files |
Resolve the connection through AgentConfig and pass its runtime value with
--endpoint; never commit it. Override the policy source with --policy-dir.
Operations
1. List Policies
Retrieve and display all registered policies from the Eunomia server:
python scripts/list_policies.py
The script:
- Connects to the Eunomia server at
EUNOMIA_ENDPOINT. - Calls
client.get_policies()to retrieve all registered policies. - Prints each policy's name, description, default effect, and individual rules with their actions.
Example output:
Successfully retrieved 5 policies:
- caddy-mcp-policy: Authorization policy for caddy-mcp MCP server (default: allow)
* Rule 'unrestricted-access': allow for actions ['list', 'execute']
2. Create Policy Files
Generate per-service policy JSON files for all known MCP servers:
python scripts/create_policies.py
The script:
- Iterates over a predefined list of MCP service names.
- Generates a policy JSON file per service in
POLICY_DIRwith:default_effect: allow(audit-mode, permissive by default)- A single
unrestricted-accessrule allowinglistandexecuteactions
- Writes each file as
{service-name}.json.
3. Push Policies to Server
Upload all local policy files to the remote Eunomia server:
python scripts/push_policies.py
The script:
- Scans
POLICY_DIRfor*.jsonfiles. - Validates each against the
eunomia_sdk.client.schemas.PolicyPydantic model. - Deletes any existing policy with the same name (idempotent upsert).
- Creates the policy on the remote server via
client.create_policy().
Policy JSON Schema
Each policy file follows this structure:
{
"version": "1.0",
"name": "{service-name}-policy",
"description": "Authorization policy for {service-name} MCP server",
"default_effect": "allow",
"rules": [
{
"name": "unrestricted-access",
"description": "All principals can list and execute tools, resources, and prompts",
"effect": "allow",
"principal_conditions": [],
"resource_conditions": [],
"actions": ["list", "execute"]
}
]
}
Fields
| Field | Type | Description |
|---|---|---|
version |
string | Policy schema version (always "1.0") |
name |
string | Unique policy name (convention: {service}-policy) |
default_effect |
allow or deny |
Fallback when no rule matches |
rules[].effect |
allow or deny |
What to do when this rule matches |
rules[].actions |
list | MCP actions: list, execute |
rules[].principal_conditions |
list | Filter by caller identity (empty = any) |
rules[].resource_conditions |
list | Filter by tool/resource name (empty = any) |
Error Handling
- Connection refused: run the AgentConfig/doctor connection check for the selected Eunomia profile; do not substitute a stored endpoint or disable TLS.
- eunomia-sdk not installed: Run
pip install eunomia-sdk. - Invalid policy JSON: The push script validates against Pydantic schemas and reports specific validation errors.
- Policy already exists: The push script deletes existing policies before re-creating (idempotent).