Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SpectraMCP compute FFT of iq_data.wav"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Honest boundary: this project evaluates and records intended actions. It
does not magically intercept every MCP call. Enforce decisions with the
Python wrapper, or make check_action a required step in your tool host.
One useful job, end to end: name a capability such as fs.write_report, get
allow, approval_required, or deny, and leave a locally verifiable audit
event. No policy daemon, account, or cloud relay is required.
# Quickstart — run the three decisions without cloning (requires uv)
uvx --from git+https://github.com/IamOumarIbrahim/governed-agent-mcp-stack governed-agent demoExpected decisions:
signal.read_file allow
fs.write_report approval_required
shell.execute deny{
"mcpServers": {
"governed-agent-gate": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/IamOumarIbrahim/governed-agent-mcp-stack",
"governed-agent-mcp"
]
}
}
}Related MCP server: sionna-mcp
Agent tools often jump from harmless reads to file writes, shell execution, or
CAD mutations with scattered if statements—or no check at all. This project
provides a small gate that can be called from Python, a shell pipeline, or an
MCP client before the risky function executes.
Instead of starting with a policy platform, you get:
A useful starter policy: read-only and in-memory work is allowed, writes require approval, and destructive or unknown capabilities are denied.
One enforcement API: Gatekeeper.enforce() raises before the wrapped
function body runs.
Evidence you can inspect: every decision is appended to SQLite with a SHA-256 hash chained to the previous event.
The best fit is an MCP server author or agent-platform engineer who needs a reviewable local safety layer today and may graduate to a larger policy system later.
🔒 Fail closed: unmatched capabilities use default_action: deny.
🧩 Exact and glob rules: express fs.read_file or families such as
fs.write_* in plain YAML.
🐍 Real enforcement: use a Python decorator or enforce() before a tool
body; denied and approval-required calls raise distinct exceptions.
🔌 Real MCP server: check_action, recent_decisions, and
verify_audit_chain run over local stdio with FastMCP.
🧾 Tamper-evident audit: changed or reordered SQLite rows fail chain verification. Context stays local and must be JSON serializable.
🤖 Automation-friendly CLI: JSON output and stable exit codes let CI, shell scripts, and tool hosts gate actions.
🧪 Useful examples, labeled honestly: offline DSP helpers and a best-effort process scanner remain as optional workloads, not product claims.
The gate belongs immediately before the code that can cause a side effect.
flowchart LR
Agent["Agent or MCP client"] --> Intent["Capability + JSON context"]
Intent --> Gate["Policy gate"]
Policy["YAML policy"] --> Gate
Gate -->|"allow"| Tool["Wrapped tool function"]
Gate -->|"approval_required"| Review["Your approval workflow"]
Gate -->|"deny"| Stop["Stop"]
Gate --> Audit[("Local SQLite hash chain")]
classDef default fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
classDef gate fill:#1e1b4b,stroke:#a855f7,stroke-width:2px,color:#fff;
class Gate gate;Approval is a decision, not an approval system. This repository signals
approval_required; your product must collect and validate human approval
before retrying the protected action.
uvx --from git+https://github.com/IamOumarIbrahim/governed-agent-mcp-stack governed-agent demouvx runs the command in an
isolated environment. Use this path to evaluate the project without changing
your current Python environment.
git clone https://github.com/IamOumarIbrahim/governed-agent-mcp-stack.git
cd governed-agent-mcp-stack
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[all,dev]"
governed-agent doctorWindows users can run .\setup.ps1 to create .venv, install the development
extras, run tests, and print the MCP client config. The script does not edit
client settings.
🔍 Verification command:
governed-agent doctor
python -m pytest -q
python -m ruff check .Expected test summary for this revision: 22 passed.
The zero-edit config near the top uses the packaged starter policy. For a policy you own:
Create a local policy:
governed-agent init --output ./my-policy.yamlPrint a config containing the current Python executable and absolute paths:
governed-agent config --policy ./my-policy.yamlMerge the printed mcpServers entry into your client's configuration and
restart the client.
The server exposes:
MCP tool | What it does |
| Evaluates and audits one capability plus optional context |
| Returns recent local decisions, newest first |
| Detects modified or reordered audit rows |
FastMCP uses stdio by default for local servers, so the client owns the server process lifecycle and no HTTP port is opened.
governed-agent check fs.write_report \
--context '{"path":"reports/result.json"}'The JSON response includes the decision, matched rule, reason, policy source, and audit event hash.
from interlock import Gatekeeper
gate = Gatekeeper(
policy_path="interlock.policy.yaml",
audit_path=".interlock/audit.db",
)
@gate.protect(
"fs.write_report",
context_factory=lambda path, content: {"path": path, "bytes": len(content)},
)
def write_report(path: str, content: str) -> None:
with open(path, "w", encoding="utf-8") as report:
report.write(content)With the starter policy, write_report() raises ApprovalRequired before
opening the file. Unknown capabilities raise ActionDenied.
version: 1
default_action: deny
capabilities:
"workspace.read_*":
mode: allow
reason: Read-only workspace tools are safe for this host.
"workspace.write_*":
mode: approval_required
reason: A human must review workspace mutations.
"shell.execute":
mode: deny
reason: This host never delegates arbitrary shell execution.Exact rules win over globs. When multiple globs match, the most specific pattern wins.
Command | Purpose | Exit behavior |
| Run one allow, approval, and deny example |
|
| Evaluate and optionally audit one action |
|
| Validate policy and audit-chain integrity |
|
| Print recent events as JSON |
|
| Verify the event hash chain |
|
| Copy the packaged starter policy |
|
| Print MCP client JSON; never edits settings |
|
| Run the stdio MCP server | Until client disconnects |
Policy or input errors return 64.
Option | Strong fit | Trade-off |
Scattered checks in tool code | One tiny application | Hard to audit and easy to apply inconsistently |
This project | Local Python/MCP prototypes that need a working gate now | Single-process, YAML rules, no identity-aware authorization |
General policy engines such as OPA or Cedar | Multi-service authorization with a dedicated policy model | More infrastructure and integration work than this starter gate |
This project is a stepping stone, not a claim that a small Python library replaces a mature organization-wide authorization system.
No transparent interception: an MCP client can ignore the gate. Use the Python wrapper or enforce the call order in the host you control.
No built-in approval UI: approval_required must feed an approval flow
outside this package.
Tamper-evident, not tamper-proof: the hash chain detects changed or reordered rows, but an attacker with filesystem access can delete the whole database or truncate its tail. Anchor hashes externally for stronger proof.
Local identity only: rules do not model users, organizations, OAuth scopes, or remote multi-tenant authorization.
Context is stored: do not pass secrets in decision context.
Optional examples are examples: spectramcp/ implements offline numeric
helpers; agentpulse/ performs best-effort process-name scanning. Neither is
a production hardware adapter or transcript telemetry platform.
governed-agent-mcp-stack/
├── interlock/
│ ├── gate.py # Enforcement API and decorator
│ ├── policy.py # Validated exact/glob policy engine
│ ├── audit.py # SQLite SHA-256 event chain
│ ├── cli.py # JSON CLI, doctor, config, audit commands
│ ├── server.py # Three-tool FastMCP stdio server
│ └── default_policy.yaml # Packaged fail-closed starter policy
├── spectramcp/ # Optional offline DSP example helpers
├── agentpulse/ # Optional local process-scanner example
├── tests/ # Unit, CLI, and in-process MCP tests
├── interlock.policy.yaml # Editable repository policy
├── GATES.md # Product and release gate checklist
└── pyproject.toml # Package metadata and console scriptsIssue | Root Cause | Resolution |
| uv is not installed | Use the clone/venv path or install uv from its official documentation |
Everything returns | No capability rule matched | Run |
Command exits with | The rule requires approval | Stop; complete your external approval flow before calling the protected tool |
Client cannot start the server | Client environment cannot find the command or policy | Run |
Audit verification fails | A stored row changed or was reordered | Preserve the DB for investigation; start a new DB only after review |
DSP imports fail | Optional NumPy extra is absent | Install |
The highest-value contributions are host adapters that make the gate unskippable, approval-flow examples, and adversarial tests for policy or audit edge cases. Start with CONTRIBUTING.md; every pull request must pass the gates in GATES.md.
MIT © 2026 Oumar Ibrahim
FastMCP · PyYAML · SQLite · NumPy
If this saved you from rebuilding the same policy gate—or one risky agent write—a ⭐ helps other MCP builders find it.
Evaluate and audit an intended tool capability.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| capability | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states that the tool 'evaluates and audits.' It does not mention whether it is read-only, what side effects it may have, what inputs are expected, or what the output schema contains. This is a minimal, non-informative description that fails to convey behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise in length but under-specified. It does not provide useful detail, so it is not effectively structured to aid an agent. The succinctness is not a virtue here because it omits essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not explain what the tool returns or how the output should be interpreted. With only 2 parameters, no parameter documentation, and no annotations, the description is far from complete for safe and correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not mention the 'capability' parameter (required) or 'context' parameter at all. The agent receives no explanation of what values to supply for these parameters or what they mean, making correct invocation difficult.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verbs 'evaluate and audit' with the object 'intended tool capability', which gives a general sense of verifying a capability. However, the phrase is vague and does not clearly define what 'capability' means or how it is audited, making it difficult to distinguish from sibling tools beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like recent_decisions or verify_audit_chain. The description offers no context, prerequisites, or exclusions, leaving the agent without direction on appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent local policy decisions, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only mentions result ordering. It does not explicitly state that the operation is read-only, nor does it describe permissions, side effects, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It clearly conveys the core purpose and an important ordering detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sparse and omits key usage details, particularly the 'limit' parameter's effect. Although an output schema exists, the lack of parameter explanation and behavioral context leaves the description incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, 'limit', with no description, and the tool description does not mention it. Since schema coverage is 0%, the description fails to compensate by explaining how to control the number of results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns recent local policy decisions with newest first ordering. The verb 'return' and resource 'local policy decisions' are specific, and the ordering distinguishes it from sibling tools like check_action and verify_audit_chain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or relationships to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the local audit log for modified or reordered rows.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the action ('check') and what it detects, but does not explicitly state whether it is read-only, what it returns, or any side effects. The verb 'check' implies non-mutating behavior, but this is implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema, the description sufficiently conveys the core purpose. It lacks details about detection methodology, but that is likely covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is complete, so the baseline 4 applies. There is no need for the description to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the local audit log for modified or reordered rows, providing a specific verb and resource. It distinguishes itself from sibling tools like check_action and recent_decisions by focusing on audit log integrity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.0.0check_actionrecent_decisionsverify_audit_chainEach tool targets a distinct aspect of the audit workflow: check_action evaluates an intended capability, recent_decisions lists past decisions, and verify_audit_chain checks log integrity. No two tools overlap in purpose, so an agent can easily select the right one.
Two tools follow the verb_noun pattern (check_action, verify_audit_chain), but recent_decisions uses an adjective_noun pattern, which is a minor deviation. The names are still descriptive and predictable.
With only 3 tools, the set is well-scoped for a focused audit and policy-decision utility. Each tool serves a clear and necessary function, and the count is within the ideal 3-15 range.
The core audit lifecycle is covered: evaluate an action, list decisions, and verify integrity. Minor gaps exist, such as no way to fetch a single decision by ID or perform detailed historical queries, but these are workable limitations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create RF signal projects from prompts, inspect graphs, and export IQ data.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Independent directory of agentic AI tools — search, compare & recommend via MCP. Read-only.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/IamOumarIbrahim/governed-agent-mcp-stack'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
