Tiny Tank MCP

A minimal, read-only MCP server for testing agent-to-tool integration. An agent (Claude, Copilot Studio, or any MCP client) looks up a tank's status from a defined source instead of making the answer up. It runs one read-only MCP tool, get_tank_status, over Streamable HTTP at /mcp. The endpoint is stateless and sends JSON responses.

The data is three synthetic tanks. There are no write operations, no connections to any other system, no auth, and no secrets.

Input is trimmed and upper-cased before validation, so tk-102 resolves to TK-102. Every result has the same six fields: tank_id, status, site, result_code, message, source.

Layout

src/business_logic.py     synthetic records, validation, lookup (no MCP dependency)
src/server.py             MCP wrapper, run options, one JSON log line per call
tests/                    unit, in-process MCP protocol, and security (SEC-01..05) tests
tools/smoke_test.py       stdlib client for a live endpoint; writes JSON evidence
tools/compare_routes.py   direct vs gateway evidence parity check (GT-05)
tools/security_check.py   black-box SEC-01..05 against a live endpoint
security/tool_manifest.sha256  pinned hash of the tool definition (SEC-01)
SECURITY.md               security declaration
docs/security_test_cadence.md  the five security cases and when to run them
docs/deployment.md        hosting and connecting an agent
docs/build_report.md      verification results
.github/workflows/ci.yml  tests + live black-box security check on every push

Related MCP server: mcp-knowledge-server

Run locally

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python -m pytest -v                 # 32 tests (15 functional + 17 security)
python -m src.server                # http://127.0.0.1:8000/mcp
python tools/smoke_test.py --out evidence/direct.json

Runtime variables

When MCP_HOST is a loopback address, the SDK applies a localhost-only Host/Origin check on its own. On any other bind, set MCP_ALLOWED_HOSTS. Otherwise no Host header check runs.

Logging

Each tool call writes one JSON line to stderr with these fields: ts, event, tool, call_id, tank_id (normalized, max 32 characters), result_code, duration_ms. Headers, tokens and other arguments are never logged.

Security

The tool declares itself read-only, non-destructive, idempotent and closed-world. It does this through standard MCP annotations and a tinytank/security-declaration block in _meta, sent both at discovery and on every call. See SECURITY.md.

The five security cases (SEC-01..05) and when they run are in docs/security_test_cadence.md. Run the independent black-box check with:

python -m tools.security_check --url http://127.0.0.1:8000/mcp --log-file server.log

Connect an agent

Once hosted at https://<host>/mcp (see docs/deployment.md):

claude mcp add --transport http tiny-tank https://<host>/mcp

For Copilot Studio, add an MCP tool with the Streamable HTTP transport and no authentication. If the agent belongs to an organization, get that organization's approval before connecting it to an external endpoint.

License

MIT