dmint-mcp

Deterministic Security Enforcement Gateway for Model Context Protocol (MCP)

dmint-mcp is an out-of-process enforcement gateway that connects AI agents to one or more Model Context Protocol (MCP) servers under deterministic, cryptographic policy control powered by Dmint Core V1.

Architecture

┌──────────────────────────────────────┐
│        AI Agent / MCP Client         │
└──────────────────┬───────────────────┘
                   │ Transport: STDIO or Streamable HTTP (SSE)
                   │ Auth: Optional Bearer token with identity binding
                   ▼
┌──────────────────────────────────────┐
│          Dmint MCP Gateway           │
│                                      │
│  - Request mapping & anti-spoofing   │
│  - Multi-server tool routing         │
│  - Request size bounds & CORS        │
│  - Sanitized error boundary          │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│           Dmint Core V1              │
│       (Frozen Security Engine)       │
│                                      │
│  - Deterministic policy evaluation   │
│  - ALLOW / DENY / APPROVAL_REQUIRED  │
│  - RFC 8785 request fingerprinting   │
│  - Ed25519 approval assertions       │
│  - Single-use atomic consumption     │
└──────────────────┬───────────────────┘
                   │ Forwarding only on ALLOW / Consumed Approval
                   ├────────────────────────────┐
                   ▼                            ▼
        ┌─────────────────────┐      ┌─────────────────────┐
        │ Downstream Server 1 │      │ Downstream Server 2 │
        │       (STDIO)       │      │  (Streamable HTTP)  │
        └─────────────────────┘      └─────────────────────┘

dmint-mcp serves strictly as the integration and protocol bridge. All authorization decisions, approval verification, and credential consumption semantics are owned authoritatively by Dmint Core.

Related MCP server: protect-mcp

Key Features

• Multi-Server Gateway: Aggregates and routes tool calls across multiple downstream MCP servers with collision avoidance.

• Bi-Directional Transports: Supports STDIO and Streamable HTTP (SSE) for both upstream agent connections and downstream server connections.

• Zero Downstream Execution on Block: Unapproved (APPROVAL_REQUIRED) or forbidden (DENY) tool calls never reach downstream server processes.

• Double-Gate Approval Retry: Retrying an approval requires an Ed25519-signed assertion that is revalidated against current policy and atomically consumed in SQLite storage before downstream tool execution.

• Strict Identity Binding & Anti-Spoofing: Binds transport authentication directly to the calling agent identity; client cannot forge or override agent_id.

• SSRF Protection: Protects remote downstream HTTP endpoints against SSRF, blocking private IP ranges, link-local addresses, and cloud provider metadata services.

• Downstream Timeout Controls: Hard bounded timeouts for connect, list, and call operations.

• Sanitized Errors: Error disclosure modes (DOG, CAT, GOD) ensure internal paths, credentials, and stack traces never leak to untrusted agents.

• CLI Artifact Compatibility: Natively loads the canonical mcp_protection.json generated by dmint-cli.

Security Model

Every incoming tool call passes through pre-execution authorization before any downstream action is permitted:

1. ALLOW: The request complies with authoritative policy. The gateway forwards the call downstream and returns the tool result.

2. DENY: The request violates policy. The gateway immediately terminates the request and returns an error. Zero downstream tool execution occurs.

3. APPROVAL_REQUIRED: The capability requires elevated authorization. The exact request is fingerprinted and persisted as a pending approval record. The gateway challenges the caller with a structured approval error. Zero downstream tool execution occurs.

4. Approval Retry: An administrative authority signs an approval assertion over the exact request fingerprint. When the agent retries the call presenting the credential:

   • The gateway verifies the Ed25519 signature and audience.

   • The current policy is re-evaluated to ensure it has not changed to DENY.

   • The approval record is atomically consumed (APPROVED -> CONSUMED) in SQLite storage to prevent replay attacks.

   • Only upon successful atomic consumption does the tool execute downstream.

Transports

dmint-mcp supports two independent transport dimensions:

Upstream (Agent-Facing)

• STDIO (stdio, default): Communicates directly over standard input and standard output. This is the zero-overhead default suited for local AI runtime processes.

• Streamable HTTP (http): Runs an ASGI HTTP server with Server-Sent Events (SSE) via Starlette and Uvicorn. Enables remote agents and multi-tenant systems to communicate over HTTP.

Downstream (Server-Facing)

• STDIO (stdio): Launches and supervises downstream MCP server subprocesses.

• Streamable HTTP (streamable_http): Connects to remote downstream MCP servers over HTTPS with strict SSRF validation and redirect prevention.

Authentication

When running the agent-facing transport over HTTP:

• Bearer Token Auth: Clients authenticate by sending an Authorization: Bearer <token> header.

• Constant-Time Verification: Tokens are verified using hmac.compare_digest to prevent timing attacks.

• Multi-Agent Identity Mapping: The gateway supports binding specific tokens to distinct agent identities (e.g. token1=agent_coder,token2=agent_reviewer).

• Safe Binding Enforced: Attempting to bind the HTTP server to a public interface (0.0.0.0 or routable IP) without authentication configured fails closed at startup.

• Wildcard CORS Defense: Wildcard CORS (*) is prohibited when authentication is enabled.

Configuration (mcp_protection.json)

The gateway configuration specifies policy provenance, approval storage, and downstream integrations:

{
  "$schema": "https://dmint.app/schemas/mcp_protection_v1.json",
  "version": "1.0",
  "server_name": "dmint-secure-gateway",
  "agent_id": "worker-agent",
  "policy": {
    "rules": [
      {
        "effect": "allow",
        "tool": "calc",
        "action": "add",
        "resource": "*"
      },
      {
        "effect": "approval_required",
        "tool": "db",
        "action": "wipe",
        "resource": "*"
      }
    ]
  },
  "approval_store": {
    "path": "./approvals.db",
    "ttl_seconds": 300
  },
  "disclosure_mode": "DOG",
  "integrations": [
    {
      "id": "calculator",
      "transport": "stdio",
      "command": "python3",
      "args": ["-m", "calculator_mcp"],
      "tools": {
        "add": {
          "capability": "calc.add",
          "discovery": "exposed"
        }
      }
    },
    {
      "id": "database",
      "transport": "streamable_http",
      "url": "https://mcp.internal.infra/mcp",
      "connect_timeout": 10.0,
      "call_timeout": 30.0,
      "tools": {
        "wipe_data": {
          "capability": "db.wipe",
          "discovery": "exposed"
        }
      }
    }
  ]
}

Command Line Interface (CLI)

Install dmint-mcp:

pip install dmint-mcp

Run over Local STDIO (Default)

dmint-mcp run --config mcp_protection.json

Or using the short flag:

dmint-mcp -c mcp_protection.json

Or via Python module invocation:

python -m dmint_mcp -c mcp_protection.json

Run over Remote HTTP

dmint-mcp run \
  --config mcp_protection.json \
  --transport http \
  --host 127.0.0.1 \
  --port 8000 \
  --auth-token "secret_token_123"

Environment variables can also configure execution:

• DMINT_CONFIG_PATH: Path to configuration file.

• DMINT_TRANSPORT: stdio or http.

• DMINT_HOST: Interface to bind (default: 127.0.0.1).

• DMINT_PORT: Port to bind (default: 8000).

• DMINT_AUTH_TOKEN: Bearer token or token mapping string.

• DMINT_LOG_LEVEL: Logging verbosity (info, debug, etc.).

Python API Quickstart

Developers can also instantiate and embed the gateway programmatically:

import asyncio
from pathlib import Path
from dmint_mcp import MCPGateway, load_protection_config

async def run_gateway():
    # 1. Load validated configuration
    config = load_protection_config(Path("mcp_protection.json"))

    # 2. Instantiate gateway
    gateway = MCPGateway(config)

    # 3. Serve over STDIO or HTTP
    await gateway.serve_stdio()

if __name__ == "__main__":
    asyncio.run(run_gateway())

Testing

Run the full test suite with pytest:

pytest -v

License

Licensed under the Apache License, Version 2.0.