flowchart TD
    A[AI assistant<br/>Claude Desktop, Claude Code,<br/>or the demo agent] -->|MCP over stdio<br/>key in the environment| S
    A2[Remote assistant or service] -->|MCP over HTTP<br/>Authorization: Bearer key| B[Bearer check<br/>401 without a valid key]
    B --> S[MCP server<br/>server.py]
    S -->|tools/list| F[Tool list filtered by role]
    S -->|tools/call| G

    subgraph G[Gateway: the single path for every call]
        direction TB
        G1[1. Rate limit per key] --> G2[2. Permission of the role]
        G2 --> G3[3. Arguments validated<br/>with Pydantic]
        G3 --> G4[4. Idempotency key<br/>already used?]
        G4 --> G5[5. Tool runs in one transaction<br/>business rules first]
    end

    G5 --> D[(SQLite<br/>customers, products,<br/>orders, refunds)]
    G -->|every call: ok, denied or error| L[(Audit log<br/>hash-chained)]
    G -->|result, or error with code and message| A

tool                  kind    permission        viewer   agent    manager
search_customers      read    customers:read    yes      yes      yes
get_customer          read    customers:read    yes      yes      yes
search_products       read    products:read     yes      yes      yes
get_order             read    orders:read       yes      yes      yes
list_orders           read    orders:read       yes      yes      yes
sales_summary         read    reports:read      yes      yes      yes
read_audit_log        read    audit:read        -        -        yes
add_customer_note     action  customers:write   -        yes      yes
create_order          action  orders:write      -        yes      yes
update_order_status   action  orders:write      -        yes      yes
request_refund        action  refunds:request   -        yes      yes
decide_refund         action  refunds:approve   -        -        yes
adjust_stock          action  inventory:write   -        -        yes

$ python -m business_mcp demo "Refund \$300 on order O00012 because the wrong items were sent"
Connected to business-tools over stdio. 10 tools offered to this key. Provider: mock.
Task: Refund $300 on order O00012 because the wrong items were sent
  1. get_order({"order_id": "O00012"})
     -> {"id": "O00012", "customer_id": "C0011", "status": "delivered", "total": 453.1, "created_at": "2026-04-10T13:14:00Z", "customer_name": "Jonas Petrov", "company": "Granite Bookshop", "lines": [{"product_id": "P029", "name...
  2. request_refund({"order_id": "O00012", "amount": 300.0, "reason": "the wrong items were sent"})
     -> {"refund_id": "R0001", "order_id": "O00012", "amount": 300.0, "status": "pending", "message": "Waiting for a manager: the amount is above your limit of 100. Tell the customer the refund is under review, not that it is do...
Answer: Refund R0001 of $300.00 on order O00012 is pending. Waiting for a manager: the amount is above your limit of 100. Tell the customer the refund is under review, not that it is done.

$ python -m business_mcp demo "Mark order O00300 as shipped" --key demo-viewer-key
Connected to business-tools over stdio. 6 tools offered to this key. Provider: mock.
Task: Mark order O00300 as shipped
Answer: I cannot do that with my access: the tool update_order_status is not available to this API key.

$ python -m business_mcp audit tail -n 5
    1 2026-10-12T12:07:04Z demo-agent     stdio  get_order            ok  order O00012
    2 2026-10-12T12:07:04Z demo-agent     stdio  request_refund       ok  refund R0001 pending, 300.0
$ python -m business_mcp audit verify
Audit log intact: 2 records. Head hash: 495d91a08606c80c436d0eddf4ce6e646fbb0dc9aed88685074285639d4eb4c2

git clone https://github.com/BelAnas/mcp-business-tools-server.git
cd mcp-business-tools-server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

pytest -q                                   # the test suite
python -m business_mcp demo "What is the status of order O00012?"
python -m evals.run_eval                    # the measurements in the table above

python -m business_mcp demo "Which products are running low?"
python -m business_mcp demo "Show sales from 2026-09-01 to 2026-09-30 by category"
python -m business_mcp demo "Add a note to customer C0005: asked for a paper quote"
python -m business_mcp demo "Mark order O00012 as cancelled"     # refused: a delivered order is final

{
  "mcpServers": {
    "business-tools": {
      "command": "/path/to/mcp-business-tools-server/.venv/bin/python",
      "args": ["-m", "business_mcp", "serve"],
      "cwd": "/path/to/mcp-business-tools-server",
      "env": { "BUSINESS_MCP_API_KEY": "demo-agent-key" }
    }
  }
}

claude mcp add business-tools --env BUSINESS_MCP_API_KEY=demo-agent-key \
  -- /path/to/mcp-business-tools-server/.venv/bin/python -m business_mcp --db /path/to/mcp-business-tools-server/data/business.db serve

python -m business_mcp serve --transport http        # http://127.0.0.1:8931/mcp
curl -s -X POST http://127.0.0.1:8931/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# {"error": "A valid API key is required: Authorization: Bearer <key>"}

export LLM_PROVIDER=openai OPENAI_API_KEY=...         # or OPENAI_BASE_URL for a local model
python -m business_mcp demo "Cancel order O00298 and tell me what happened to the stock"
python -m evals.live_check                            # 8 tasks judged by the database

python -m business_mcp keys create --label support-bot --role agent   # printed once, stored as a hash
python -m business_mcp keys list
python -m business_mcp keys revoke --label support-bot

business_mcp/
  config.py        settings read from the environment
  db.py            SQLite schema and connections (read tools get a read-only connection)
  seed.py          the synthetic wholesaler, generated from a fixed seed
  auth.py          API keys (hashed), roles and their permissions
  errors.py        the error codes tools return
  ratelimit.py     per-key call limit
  audit.py         hash-chained audit log and its verification
  gateway.py       the single path for every call: checks, transaction, audit
  policy.py        the policy text served as an MCP resource, generated from the code
  server.py        the MCP server: stdio, HTTP with bearer check, resources, prompts
  cli.py           serve, seed, keys, audit, tools, demo
  tools/
    registry.py    one entry per tool: argument model, permission, handler
    read.py        the six read tools
    write.py       the seven action tools and the business rules
agent/
  providers.py     offline scripted provider and OpenAI-compatible provider
  loop.py          the agent loop over an MCP client
  run.py           the demo command
evals/
  run_eval.py      permission matrix, guardrails, audit, HTTP auth, latency, agent tasks
  live_check.py    the demo agent with a real model, judged by the database
  report.json      the full report of the last evaluation run
tests/             pytest suite: gateway rules, MCP over three transports, agent