mantora

Mantora serves as an open-source run log proxy for MCP agents, providing a shielded, replayable record of agent interactions with databases. It runs as a proxy between your MCP client and your target data stores, logging each SQL statement and tool call, while applying a protective mode with guardrails to block or warn on dangerous queries by default. You can run its control room UI to manage connections, switch targets on the fly, and export session evidence for sharing or auditing. This makes agent behavior verifiable and repeatable, which is especially helpful for debugging, security reviews, and PR-ready reports.

To use Mantora with an MCP client, configure the client to point at Mantora’s proxy as your mcpServer. In Mantora’s Control Room, create targets for your databases (DuckDB, Postgres, etc.), activate the desired target, and switch targets without restarting the agent. When a query is executed, Mantora first checks the safety policy, then forwards the query to the database, logs the session asynchronously, and relays the results back to the agent. You can also export raw trace data or generate a Markdown-friendly report for sharing in PRs or Slack.

Operationally, Mantora provides: (1) a protective mode with safe defaults for destructive patterns, (2) session logging that captures SQL and tool calls for auditability, and (3) a configurable control room UI for managing targets and viewing live logs. The system is designed to be read-only safe out of the box, making it practical for ongoing monitoring and collaboration across teams.

Prerequisites:

• Python installed (recommended version per Mantora docs)
• pipx available to install Mantora with optional extras

Step-by-step installation:

1. Install Mantora with optional adapters (DuckDB, Postgres) via pipx:

pipx install "mantora[duckdb,postgres]"

2. Start Mantora’s control room UI (if applicable) and run the proxy by configuring your MCP client to use Mantora as the mcpServer. Mantora provides a dashboard to manage targets and view logs. The typical usage involves launching Mantora in the environment where your agent runs and then directing the agent to connect to Mantora:

# Example: start the Mantora proxy (depending on how Mantora exposes commands)
mantora up

3. Configure Targets in Mantora:

• Open the Control Room (default http://localhost:3030).
• Create a new target for your database (DuckDB, Postgres, etc.).
• Activate the target you want your agent to use.

4. Configure your MCP client to point to Mantora:

• In your client config (e.g., mantora.toml or client JSON), set the mcpServers.mantora.command to mantora and args to ["mcp"] as in the example below:

{
  "mcpServers": {
    "mantora": {
      "command": "mantora",
      "args": ["mcp"]
    }
  }
}

Prerequisites notes:

• Ensure network access between the agent, Mantora proxy, and target databases.
• Review Mantora configuration docs for safety policy and storage paths, which may require a mantora.toml file for advanced setup.

Tips and caveats:

• Mantora defaults to a protective mode that can block or warn on destructive SQL patterns (e.g., DROP, TRUNCATE). You can customize the safety policy via configuration (mantora.toml) to adjust what is allowed or blocked.
• All data is stored locally by Mantora; review Privacy docs for storage practices and data retention.
• To share or archive sessions, use the UI to export JSON traces or download Markdown reports suitable for PRs or documentation.
• If you need to adjust ports or enable additional features, consult the Configuration Guide (docs/configuration.md) for flags, ports, and policy overrides.
• If you encounter issues with targets or the UI, verify that the Control Room is running and that the agent’s config points to Mantora’s mcp server endpoint.