ops-agent-mcp
Click on "Deploy 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., "@ops-agent-mcp Which deals are stuck in negotiation above R$ 100k?"
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.
ops-agent
An LLM agent that turns natural-language requests into audited, permission-gated actions on business systems — built on Anthropic tool use and exposed both as an HTTP API and as an MCP server.
"Which deals are stuck in negotiation above R$ 100k?" →
list_deals→ answer. "Close deal_102 as won, contract signed." →update_deal_stage→ refused unless writes are explicitly enabled, and either way the attempt is in the audit log.
Why this exists
Most "AI agent" demos let the model call anything with whatever arguments it produces. That is fine for a notebook and unacceptable for a CRM or a finance system. This project is a small, complete reference for the boring parts that make an agent deployable:
Allowlisted tools with schema-validated inputs. The model is treated as an untrusted client; every argument goes through Pydantic before touching a database.
Write gating. Mutating tools need an explicit opt-in per request and a global switch. A prompt injection hidden in a ticket subject cannot promote itself to a write.
Audit trail. Every tool call — allowed or refused — is appended to a JSONL log with timing, outcome and PII redaction.
One registry, three surfaces. The same
ToolRegistryproduces the Anthropic tool schema, the MCP tools and the test fixtures, so they cannot drift apart.Testable without network. The Anthropic client is injected behind a protocol; the agent loop is covered by unit tests with a scripted fake. Behavioural evals run against the real model when you want them to.
Related MCP server: GTM MCP Server
Architecture
flowchart LR
U[User / CLI / HTTP] -->|message| A[Agent loop]
M[MCP client<br/>Claude Desktop, IDE] -->|tool call| S[MCP server]
A -->|messages + tool schema| LLM[Claude<br/>Messages API]
LLM -->|tool_use blocks| A
A -->|validate · gate · execute| R[ToolRegistry]
S --> R
R --> T1[CRM tools<br/>accounts · deals · pipeline]
R --> T2[Ticket tools]
T1 & T2 --> DB[(SQLite<br/>synthetic data)]
R -->|every call| AUD[(Audit log<br/>JSONL, redacted)]Request lifecycle
Agent.run()sends the system prompt, the user message and the registry's tool schema.For each
tool_useblock the model returns, the registry checks the allowlist, refuses mutating tools when writes are not permitted, validates arguments, and executes.Results (or structured errors with
is_error=true) go back to the model astool_resultblocks. The loop repeats until the model answers ormax_iterationshits.Each tool call is recorded in the audit log before the loop continues.
Quickstart
git clone https://github.com/ramonpalopoli/ops-agent && cd ops-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env # add your ANTHROPIC_API_KEY
# Ask something (read-only by default)
ops-agent "How much open pipeline do we have, by stage?"
# A write is refused until BOTH switches are on:
ops-agent "Move deal_101 to negotiation, customer agreed on scope" --allow-writes
OPS_AGENT_ALLOW_WRITES=true ops-agent "Move deal_101 to negotiation, customer agreed on scope" --allow-writesThe database is created and seeded with synthetic accounts, deals and tickets on first run
(data/ops.db). No real companies or people are involved.
HTTP API
export OPS_AGENT_API_TOKEN=$(python -c "import secrets;print(secrets.token_urlsafe(48))")
make api # uvicorn on 127.0.0.1:8000
curl -s http://127.0.0.1:8000/v1/chat \
-H "Authorization: Bearer $OPS_AGENT_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "Which tickets are urgent?"}'
curl -s http://127.0.0.1:8000/v1/audit?limit=10 -H "Authorization: Bearer $OPS_AGENT_API_TOKEN"Route | Auth | Purpose |
| none | liveness |
| bearer | run the agent; body |
| bearer | last N audit events |
MCP server
Expose the same tools to any MCP client. Writes are controlled solely by
OPS_AGENT_ALLOW_WRITES on the server side — a client cannot escalate itself.
ops-agent-mcp # stdio transportClaude Desktop config: see mcp.example.json.
Tools
Tool | Writes | Input (validated) |
| no |
|
| no |
|
| no | optional |
| no | — |
| no | optional |
| yes |
|
| yes |
|
Adding a tool = one Pydantic model + one handler + one register() call in
src/ops_agent/tools/__init__.py. It shows up in the API, the MCP server and the schema
tests automatically.
Tests and evals
make test # 33 unit/integration tests, no network
make lint # ruff
make evals # behavioural evals against the real model (needs ANTHROPIC_API_KEY)Unit tests cover the agent loop (tool round-trip, write gating, iteration cap, error surfacing), every tool (including a SQL-injection attempt and LIKE-wildcard escaping), the HTTP API (auth, bounds, headers) and the MCP surface.
evals/scenarios.json asserts on behaviour rather than exact wording: which tools were
called, which were avoided, whether a refused write was reported honestly, and whether an
instruction smuggled into the prompt was ignored. Add a scenario, run make evals, ship.
Security decisions
Decision | Why |
Tool allowlist + Pydantic validation of every argument | The model is an untrusted client. Unknown tools and malformed arguments are rejected before any I/O. |
Parameterised SQL everywhere; | CWE-89. User text never reaches an identifier or unbound position. |
Writes require request opt-in and | Fail-secure default; defence in depth against prompt injection. |
Iteration cap | Bounded cost and latency; no runaway loops. |
Audit log with e-mail / phone / CPF redaction | CWE-532, LGPD: reviewable without leaking personal data. |
Bearer token compared with | CWE-208 timing attacks; weak-token misconfiguration fails at startup. |
Generic error responses; details only in server logs | CWE-209. |
| Baseline hardening for a JSON API. |
Random ticket ids ( | IDOR hardening (CWE-639). |
Secrets only via environment / git-ignored | CWE-798. |
Known limitations, on purpose: single SQLite file (swap for Postgres by changing db.py),
no per-user identity on the API (add OIDC in front of it), no rate limiting (put it at the
gateway), and the system prompt is a mitigation, not a control — the controls are in code.
Project layout
src/ops_agent/
agent.py # Messages API loop, guardrails, audit hooks
api.py # FastAPI surface
mcp_server.py # MCP surface (same registry)
cli.py # ops-agent CLI
config.py # pydantic-settings, validated at startup
db.py # SQLite schema + synthetic seed
audit.py # JSONL audit log with PII redaction
tools/
registry.py # allowlist, validation, write gating
crm.py # accounts, deals, pipeline
tickets.py # support tickets
tests/ # pytest, offline
evals/ # behavioural scenarios against the real modelRoadmap
Postgres backend and connection pooling
Per-user identity on the API and per-tool permissions (RBAC)
Streaming responses
Eval metrics over time (pass rate, tool precision) in CI
License
MIT — see LICENSE.
Available Tools
7 toolscreate_ticketA
Open a support ticket for an account. WRITES DATA: only call when the user explicitly asked to create a ticket. [writes data] Arguments: {"account_id": {"description": "e.g. acc_002", "pattern": "^acc_[0-9]{3,6}$", "title": "Account Id", "type": "string"}, "subject": {"maxLength": 140, "minLength": 5, "title": "Subject", "type": "string"}, "priority": {"default": "medium", "enum": ["low", "medium", "high", "urgent"], "title": "Priority", "type": "string"}}
Inputs: arguments. Returns: result
get_dealA
Get one deal by id, including its account and recent stage history. Arguments: {"deal_id": {"description": "e.g. deal_101", "pattern": "^deal_[0-9]{3,6}$", "title": "Deal Id", "type": "string"}}
Inputs: arguments. Returns: result
list_dealsB
List deals, optionally filtered by pipeline stage, ordered by amount. Arguments: {"stage": {"anyOf": [{"enum": ["qualification", "proposal", "negotiation", "closed_won", "closed_lost"], "type": "string"}, {"type": "null"}], "default": null, "description": "Filter by pipeline stage", "title": "Stage"}, "limit": {"default": 10, "maximum": 25, "minimum": 1, "title": "Limit", "type": "integer"}}
Inputs: arguments. Returns: result
list_open_ticketsA
List open support tickets, most urgent first. Optional priority filter. Arguments: {"priority": {"anyOf": [{"enum": ["low", "medium", "high", "urgent"], "type": "string"}, {"type": "null"}], "default": null, "description": "Filter by priority", "title": "Priority"}, "limit": {"default": 10, "maximum": 25, "minimum": 1, "title": "Limit", "type": "integer"}}
Inputs: arguments. Returns: result
pipeline_summaryC
Aggregate deal count and BRL total per stage, plus open pipeline total. Arguments: {}
Inputs: arguments. Returns: result
search_accountsA
Find customer accounts by (partial) name. Returns id, segment, city, owner. Arguments: {"query": {"description": "Account name fragment", "maxLength": 80, "minLength": 1, "title": "Query", "type": "string"}, "limit": {"default": 10, "maximum": 25, "minimum": 1, "title": "Limit", "type": "integer"}}
Inputs: arguments. Returns: result
update_deal_stageA
Move a deal to another pipeline stage. WRITES DATA: only call when the user explicitly asked for the change and provided a reason. [writes data] Arguments: {"deal_id": {"pattern": "^deal_[0-9]{3,6}$", "title": "Deal Id", "type": "string"}, "stage": {"enum": ["qualification", "proposal", "negotiation", "closed_won", "closed_lost"], "title": "Stage", "type": "string"}, "reason": {"description": "Why the stage is changing (audited)", "maxLength": 280, "minLength": 5, "title": "Reason", "type": "string"}}
Inputs: arguments. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct resource and action: tickets have create/list, deals have get/list/update/pipeline summary, and accounts have search. There is no meaningful overlap that would cause an agent to select the wrong tool.
Most tool names follow a clear verb_noun pattern: create_ticket, get_deal, list_deals, list_open_tickets, search_accounts, update_deal_stage. The one deviation is pipeline_summary, which uses a noun phrase rather than an action verb, but the naming remains readable and predictable overall.
Seven tools is a well-scoped set for an ops agent handling accounts, deals, and support tickets. Each tool covers a necessary operation without redundancy or bloat.
The deal workflow is reasonably covered with list/get/stage updates and pipeline totals, but ticket support is incomplete: there is no way to fetch a single ticket, update it, or close/resolve it. Account coverage is also limited to search, with no account detail endpoint.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
An MCP gateway for teams deploying AI tools at scale to employee-facing and headless agents.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to securely call enterprise MCP tools with tenant-scoped RBAC, human approvals, audit logging, and multi-tool workflows across customer, order, document, and ticket data.-
- AlicenseAqualityCmaintenanceEnables AI agents to perform go-to-market workflows such as company and contact enrichment, CRM querying, and controlled, audited writes to a CRM through MCP tools callable from any MCP client.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to ask bilingual data questions, inspect database tables and schemas, and execute validated read-only SQL through exposed tools.MIT
- AlicenseNot gradedqualityBmaintenanceEnables chat, document search (RAG), and a declarative SQL tool builder over MCP so any client can use these capabilities.AGPL 3.0