Access receipt for MCP

A reference lab for enforcing identity-aware tool access in an MCP server.

This is a distilled version of a disposable-tenant lab. The lab question was practical: if an AI agent can reach enterprise security evidence, what proves the caller is allowed to use each tool? The answer here is deliberately plain:

1. verify the caller or agent route,
2. map identity evidence to local permissions,
3. expose only the matching MCP tools,
4. test the refusal cases.

This is not a production platform. It is a runnable pattern for access receipts: identity in, scoped tools out, and denial paths that do useful work.

Architecture

identity route -> token / authorization evidence -> verifier -> permissions -> MCP tool tags -> read-only data

The same permission ladder is used for all routes so the interesting variable is the identity plumbing, not the downstream tool contract.

Design constraints:

• the server exposes read-side evidence only,
• no arbitrary SQL tool is published,
• raw evidence is behind maester.raw,
• analysis tools return summary-shaped fields, not raw result payloads,
• Auditor is powerful, not magical; mutation remains denied.

Permission model

Role	Permissions	Typical tools	Explicit refusals
Reader	maester.read	whoami, list_runs, get_run_summary	failed-test analysis, raw detail
Analyst	maester.read, maester.analyse	Reader tools plus get_failed_tests, get_test_history, compare_runs	raw result detail
Auditor	maester.read, maester.analyse, maester.raw	Analyst tools plus get_result_detail	mutation, arbitrary SQL

Negative tests are part of the design, not decoration. If Reader can analyse, Analyst can read raw evidence, or Auditor can mutate tests, the architecture has become a suggestion box.

Routes covered

• Entra RBAC: app roles become local Maester permissions.
• Copilot Studio / Agent ID: the agent route still resolves to backend permissions.
• Okta XAA / ID-JAG: authorization evidence travels to the MCP server and is verified there.

Raw-ish examples

examples/ contains a deliberately small set of sanitised raw lab artefacts. These are the files that help a reader understand the access pattern; the rest of the lab trail was noise with better timestamps.

examples/entra-rbac/
  resource-app-create-body.raw.example.json       # resource app manifest shape: scopes, app roles, token version
  resource-app-current-summary.raw.example.json   # resulting resource/service-principal settings
  delegated-rbac-setup.raw.example.json           # delegated client, consent and role-assignment shape

examples/agent-id/
  agent-blueprint-created.raw.example.json        # Agent ID / blueprint object shape
  connector-oauth-client-created.raw.example.json # OAuth client used by the connector/runtime path
  redirect-and-user-role-assignments.raw.example.json
  copilot-mcp-connector-created.raw.example.json  # Copilot Studio MCP connector shape

examples/okta-xaa/
  custom-as-idjag-contract.raw.example.json       # authorization-server and ID-JAG contract shape
  role-matrix-passed.raw.example.json             # Reader / Analyst / Auditor validation result
  runtime-real-idjag-reader-smoke.raw.example.json

The examples are not copy-paste deployment recipes. They are shape references: what objects existed, which fields mattered, and where authorization evidence showed up.

Run locally

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
maester-ingest --source data/source --db data/maester.duckdb
python -m pytest tests -q
python scripts/duckdb/verify_demo.py

Start the MCP server with auth disabled:

MAESTER_MCP_AUTH_PROFILE=none maester-mcp

Or with synthetic local demo tokens:

MAESTER_MCP_AUTH_PROFILE=synthetic maester-mcp
# reader-token, analyst-token, auditor-token are local examples only

Sanitisation

The included data is a sanitised Maester-shaped demo set. The original private seed database is not included. data/maester.duckdb is generated locally from data/source/ and ignored by git.

The sanitisation pass replaces organisation names, user-like values, GUIDs, email-shaped values, local paths and policy names with deterministic demo values. Run the verification gate:

python scripts/duckdb/verify_demo.py

Publishing rule: configuration shape is useful; raw tenant history is not.

What is intentionally absent

• no live tenant credentials,
• no private keys,
• no production evidence,
• no arbitrary SQL tool,
• no write-side Maester controls,
• no historical lab logs, agent transcripts, deployment state, BOX notes or tenant-specific handoffs.

The useful part is the boundary, not the plumbing souvenirs.

Repository map

src/maester_mcp/        FastMCP server, auth verifiers, read-only DuckDB access
tests/                  permission, transport, ingestion and denial tests
sql/                    schema, views and verification SQL for demo evidence
data/source/            sanitised Maester-shaped source JSON
data/maester.duckdb     generated local demo database, ignored by git
examples/               sanitised raw-ish config and lab artefact shapes

Related notes and videos

• Project note: https://iam.felixelliott.com/posts/mcp-reference-architecture/
• Intro: https://youtu.be/mSMquGtJ2Tk
• Entra RBAC: https://youtu.be/8XjDbdLgbRw
• Agent ID: https://youtu.be/vh8lkvPZx0k
• Okta XAA: https://youtu.be/Z7I1Y72CXOc
• Code walkthrough: https://youtu.be/IWNy2_jZ0VQ