MTG Assistant Gateway

Overview · Quick start · Documentation · Features · How it works · Security · Repository · Development · License

A self-hosted Model Context Protocol (MCP) server for Magic: The Gathering. You run it in Docker, on one machine with Compose or on a Swarm, for you and whoever you invite. Each person adds one URL to Claude or ChatGPT and signs in with their own account. From there their assistant can look up cards and Commander data, goldfish a deck, and edit their own Archidekt decks. It never changes a deck until that person has said yes to the exact change.

Contents

• Overview

• Quick start

  • Running a gateway

  • Using a gateway someone gave you

• Documentation

• Features

  • Status

• How it works

• Security model

• Repository layout

• Development

• License

Related MCP server: architecture-map MCP server

Overview

• Two kinds of people use it.

  • The operator deploys it and decides who gets in.

  • Users connect their assistant and link their Archidekt account.

• What it runs on: three Docker containers (the gateway, Mystic Forge and ntfy) and a fourth for Forge (on by default, can be turned off), all for amd64 or arm64 (so a Raspberry Pi is fine), behind any HTTPS reverse proxy, with any OpenID Connect identity provider handling sign-in. What hardware it needs, and how long a test takes: docs/HARDWARE.md.

  • Deploy with Docker Compose on one machine, or a Docker Swarm stack (Portainer optional).

  • Tested end to end with Swarm, Authentik and an nginx proxy in CI. Examples for Caddy, Traefik and nginx are included, plus Nginx Proxy Manager steps; Keycloak, Authelia, Zitadel, Pocket ID and others have setup notes but haven't been tested with the gateway yet.

  • The picture: docs/ARCHITECTURE.md.

• Which assistants: Claude (web, desktop, iOS, Android) and ChatGPT (web), plus any MCP client that does OAuth. What works where, and the limits, are in docs/CONNECT.md.

• On a phone: the pages work in any browser. There is also an Android app that each gateway can hand out itself (on its setup page, /install?for=android, once the app file is in the image or added by the operator), adding a camera scan screen with torch brightness that lays itself out around a foldable's hinge (docs/ANDROID.md).

• What it talks to: Archidekt for decks, Scryfall for cards, and an internal Mystic Forge container (no published port) for research and simulation. Mystic Forge pulls from EDHREC, Commander Spellbook and the Comprehensive Rules.

• Accountability: every tool call is tied to whoever signed in, and every deck change lands in an audit log.

Quick start

Running a gateway

You need a machine with Docker, a domain name, and an OpenID Connect identity provider you control (Authentik, Keycloak, Authelia, ...).

1. Pick a guide and work through it top to bottom:

   • One machine: docs/DEPLOY-COMPOSE.md. Plain docker compose, with an optional Caddy that gets the HTTPS certificate for you.

   • Docker Swarm, with or without Portainer: docs/DEPLOY.md.

   Both go in the order you'll need things: identity provider, secrets, settings, start, proxy, then a quick check that it all works. Identity provider details are in docs/IDP-AUTHENTIK.md and docs/IDP-OTHERS.md; proxy details in docs/REVERSE-PROXY.md.

2. Optional: if you use Claude Code, the mtg-gateway-operator plugin walks you through the same steps and generates the secrets for you. See docs/PLUGIN.md.

3. Keep docs/OPERATIONS.md handy for running it: updates, backups, adding and removing people, and turning Archidekt writes on or off.

4. To invite someone, give them an account in your identity provider, then send them your gateway's address and docs/ONBOARDING.md.

Using a gateway someone gave you

1. Follow docs/ONBOARDING.md. It takes about ten minutes and all you need is a browser and the AI app you already use.

2. The quickest way in is the install page on the gateway itself: https://<gateway>/install. More on that in docs/PLUGIN.md.

Documentation

Screenshots of the browser pages are in docs/screenshots/.

Features

• Sign in. Users sign in from Claude or ChatGPT with OAuth, through the operator's identity provider. The whoami tool shows who's signed in.

• Research. Card search, prices, rulings, the Comprehensive Rules, EDHREC, Commander Spellbook combos, precons, deck validation and goldfish simulation.

  • These come from Mystic Forge. The gateway only passes through tools on an allowlist, and always as the signed-in user. Mystic Forge tools that duplicate a gateway tool are hidden, so each job has exactly one tool (see One tool per job).

  • Mystic Forge features that keep per-user state (watchlists, its own saved reports, interactive games) stay hidden until the gateway can track who owns them. Saved reports are covered by the gateway's own deck reports below, and the gateway has its own watchlists, off unless the operator sets MTG_WATCHLISTS_ENABLED=true.

• Deck import. Three ways to read a deck. Counts leave out the maybeboard and sideboard.

  • get_deck reads any public or unlisted Archidekt deck from a link (as plain text, statistics only, card rows, Archidekt import text or everything: its view);

  • parse_decklist reads a pasted list (lines that are not cards, such as a Total: 100 footer, are skipped and listed back);

  • parse_deck_export reads an Archidekt CSV export.

• Your decks. Link your Archidekt account once on the /account page. After that, list_my_decks (filter by name, format or folder) lists your decks and get_deck reads them, private ones included (its owner says whose deck it is). The gateway refreshes the stored Archidekt session on its own when it is about to expire or Archidekt rejects it, so a link lasts until Archidekt refuses the refresh too; each refresh is audited.

• Deck statistics and bracket estimate. deck_stats computes the mana curve, colour pips against mana sources, types, rarities, lands, average mana value, price total, format legality problems, salt, game changers, tutors, extra turns and mass land denial from Archidekt's own card data, plus Archidekt's own Estimated Bracket worked out from those flags, rule for rule as archidekt.com does it, and the structural checks (deck size for the format, commander zone, colour identity, singleton rule, uncategorised rows). A bracket set on the deck is the deck's bracket; the estimate says what the cards suggest, and the tools say so.

• Deck reports and history. run_deck_report stores the statistics together with a decklist validation and a goldfish simulation (when Mystic Forge is up; the simulator's options such as annotations, seed, turns, opponents and mulligan rules pass through; a deck without a commander and with 60 or more cards plays a 60-card game) so a deck's numbers can be followed over time with list_deck_reports and get_deck_report, or on the /history page next to the deck's proposals and snapshots.

• Compare decks. compare_decks lists the cards added, removed and changed between any two of: an Archidekt deck, a snapshot (get_snapshot shows one in full) or a pasted list, with the change in the statistics, a precon-style summary (cut and added percentages, basic lands apart) and, on request, a paired goldfish A/B of the two.

• Safe writes. Every edit starts as a proposal:

  • propose_deck_changes (edit a deck), propose_new_deck (build one from a card list, a pasted list or a CSV; it warns about a deck size the format does not allow) and propose_deck_details (name, description, format, bracket, privacy, folder, tags, cover) save the exact diff and a review link.

  • The user approves it: on the card the AI app shows next to the proposal (Claude on the web, desktop and phones; ChatGPT), with the Apply button on the review page, or, when the member chose a Semi-auto or Full-auto approval mode on their Account page, the assistant applies it with apply_proposal. The card's Approve button carries a one-time code the assistant never sees, so a tricked assistant can't press it.

  • For an edit, the gateway checks the change still does what was reviewed on the deck as it is now, saves a snapshot, makes the change, then reads the deck back to confirm it. With backups on (the operator's setting), it first also puts a private backup copy of the deck in the user's "MTG Gateway backups" folder on Archidekt; the deck page's own saves, Card search's Add to deck, and the deck editor's save with its backup box unticked make none.

  • Undo is the same flow in reverse: list_snapshots, then propose_restore_snapshot, which puts every card back as it was (printing, foil, quantity, categories, commander, sideboard and maybeboard, color tag and custom mana value).

  • A pending proposal the user no longer wants is closed with reject_proposal or the Reject button.

  • Every step is audited and limited to the signed-in user.

• Companion pages. A home page with the full navigation, /decks, /search (public decks on Archidekt by name, commander, format, colours or owner, and /users/{name} for one person's decks), /collection, /scan, /history, /activity and /guide are a phone-friendly deck view and editor behind the same sign-in: browse, search and open decks as text, stacks or grid (touch works: tap to fan a stack, press and hold to move a card between categories), see statistics, run a report, edit quantities, categories and additions (your own saves go straight to Archidekt, with a snapshot first), and look back over proposals, snapshots and reports. They are also the pages the Android app wraps.

  • Everything Archidekt's own deck page offers is there for your own decks: the editor also edits maybeboard and sideboard rows and takes a pasted list; the settings page sets the cover image, deck tags and folder; /folders creates and renames folders; Delete deck asks you to type the deck's name and keeps a snapshot first (and, with backups on, a backup copy on Archidekt). /precons lists every preconstructed deck Archidekt knows, by set. The assistant reaches folder, tags and cover only through a propose_deck_details proposal you approve. It can propose deleting a deck or creating a folder, but only your own press applies those; renaming folders is yours alone, on the Folders page.

• Collection. The cards you own, which is your Collection on Archidekt shown and edited through the gateway (nothing about them is stored here): add by name or from a scan, count copies, set a card's finish, condition, language and price paid, filter, export CSV. Owned cards get a green dot on every deck page. list_collection and propose_collection_changes (a proposal, approved like a deck edit, on the in-chat card too, and read back after it is applied) give the assistant the same.

• Likes, bookmarks, follows and comments. Archidekt's social buttons on every deck and user page, each behind a confirmation and sent under your own Archidekt name; your own comments can be edited and deleted, and other people's voted on. The assistant can propose the same (propose_deck_social, propose_comment), but you apply each one yourself, in every approval mode.

• Adaptive layout. Bottom tab bar on phones, a navigation rail from 600 px on touch screens and in the Android app, the desktop bar in wider browsers; the layout follows the live window, so a foldable, split screen or the browser's "Desktop site" switch re-flows at once.

• Profile pictures. The account icon shows each member's picture from the identity provider (Gravatar, or a picture uploaded to Authentik), fetched by the gateway, or their initials. See docs/IDP-AUTHENTIK.md.

• Admin page. Members of MTG_ADMIN_GROUP get /admin (they don't also need MTG_REQUIRED_GROUP): who has signed in, their activity, per-day usage counts, a System card (version, database size and schema, newest backup and newest backup copy, the research service's state), and buttons to disable or enable an account, revoke its tokens and sessions, unlink Archidekt, or delete everything the gateway keeps about a person. Unset, the page does not exist. Details in docs/OPERATIONS.md.

• JSON API. Everything the tools and pages do is also under /api/v1 for app builders, with the same sign-in and the same proposal flow. See docs/API.md.

• Cards in the chat. Where a person has to pick or press, the tool result comes with an interactive card (MCP Apps; Claude on the web, desktop and phones, ChatGPT as reported): the printings of a card as pictures to tap, the cards read from photos or a list to keep or drop, the proposal with Approve and Reject, and the waiting changes with Apply all. Other answers come as plain text, so a long chat stays light. A pick on the printings or recognised-cards card goes back to the assistant as plain text and never changes anything by itself; only Approve, Reject and Apply all act, each with the card's one-time code. Bulky data reaches the card through a ten-minute signed link, not through the model.

• Card scanning. The /scan page reads physical cards with your phone camera. Text recognition runs on the phone, no third-party app needed. The scanned list goes into your collection, into one of your decks or into a new deck. resolve_cards turns card names read from photos into exact cards.

• One-link setup. The gateway serves its own assistant plugin and an install page at /install.

One tool per job

No two assistant tools offer the same capability. Where Mystic Forge has a tool that does what a gateway tool already does, the Mystic Forge one is hidden (an assistant that calls it is told which tool owns the job), so an assistant never has to guess which one to use:

A test pins the hidden list, and the tool descriptions say who owns what.

Status

The gateway is in testing: versions below 1.0.0 can still change in small ways between releases (docs/VERSIONS.md).

How it works

The full picture, with diagrams, is in docs/ARCHITECTURE.md. In short:

Claude / ChatGPT / browser ──HTTPS──▶ reverse proxy ──▶ mtg-gateway ──internal network──▶ Mystic Forge
                                                          ├─ OAuth 2.1 authorization server for MCP clients
                                                          │    (client registration or metadata documents, PKCE, refresh, revoke)
                                                          ├─ login handed off to your identity provider (OIDC)
                                                          ├─ MCP endpoint at /mcp; JSON API at /api/v1
                                                          ├─ browser pages /account, /proposals, /scan, /decks, /history, /activity, /admin, /install
                                                          ├─ Archidekt adapter (paced, per-user sessions) ──▶ archidekt.com
                                                          └─ SQLite on local disk, nightly backup export

• The gateway is its own OAuth server.

  • An AI client either registers itself, or identifies itself with a Client ID Metadata Document URL. The gateway fetches that document under tight network rules.

  • The client sends the user to /authorize. If the client identified itself with a metadata document, the user first sees a page naming the client and where the sign-in returns to.

  • The gateway then sends the browser to your identity provider and, once that's done, hands the client its own opaque tokens.

• One identity per person. A single confidential OIDC client at your identity provider covers every AI client, so each person is the same user across Claude, ChatGPT and the browser pages.

• No site details in the code. Everything deployment-specific comes from environment variables and Docker secrets.

Security model

• Who can sign in is decided in your identity provider, through the application binding and groups. The gateway also requires a specific group (MTG_REQUIRED_GROUP) and refuses to start without one unless you opt out with MTG_ALLOW_ANY_IDP_USER=true.

• Membership is checked live. Before serving a request, the gateway asks the identity provider whether the person is still in the group (cached for a few seconds, MTG_MEMBERSHIP_CHECK_TTL). Take someone out of the group, or deactivate them, and their next request fails: their tokens and sessions are revoked, and a removal from the group revokes their Archidekt link too (at that next request; press Disable on the admin page as well to delete it at once, docs/OPERATIONS.md). If the provider can't be reached, requests are refused rather than let through. With Authentik this needs the offline_access scope mapping (docs/IDP-AUTHENTIK.md).

• Sign out on all my devices (on the /logout page) ends every browser and app session, and for an hour the next sign-in on that device asks for the password again.

• Tokens: /mcp only accepts tokens the gateway issued itself, so a token straight from the identity provider is rejected.

  • Tokens and registered clients' secrets are stored hashed.

  • Refresh tokens rotate, and reusing an old one kills the whole chain.

  • Authorization codes are single-use and tied to PKCE.

  • Clients can only register https return addresses, or http on localhost.

• Archidekt passwords are used once to get a session and never stored.

  • The session is encrypted with a key that lives in a Docker secret, and no page, admin tool or log shows it. Backups leave it out altogether (and the identity provider's tokens too), so after a restore members sign in again and relink Archidekt.

  • That doesn't protect against whoever runs the server, who holds the key; users are told so on the Account page, and tick a box before linking.

• Deck changes need the user's own yes. Text found in decks or tool output is never treated as an instruction to edit. Each proposal shows which app made it, and disconnecting an app rejects its pending proposals. An app connected with the read-only scope mtg.read can't change anything.

• Limits. Sign-in attempts are limited per network, metadata-document fetches per site, and Archidekt actions per member (MTG_ARCHIDEKT_CALLS_PER_10_MIN), so neither a flood nor a looping assistant can wear the gateway or Archidekt down. Archidekt requests from everyone together are spaced out and capped per minute, repeat reads are briefly cached, and "slow down" answers are honoured.

• Mystic Forge has no published ports and no login of its own. Only the gateway can reach it.

Repository layout

Development

python -m venv .venv && . .venv/bin/activate
pip install -c constraints.txt -e ".[dev]"
python scripts/fetch_ocr_assets.py                 # the /scan page's OCR files
python -m playwright install --with-deps chromium  # the browser tests
ruff check src tests scripts docker/forge && ruff format --check src tests scripts docker/forge && pytest -q -n auto

Without the OCR files or a Chromium the tests that need them are skipped, not failed, so a local run can pass where CI fails. CONTRIBUTING.md has the details and the end-to-end suite.

Contributions are welcome: see CONTRIBUTING.md and the code of conduct. Please report security problems privately, as described in SECURITY.md. Notable changes are in the CHANGELOG.

License

PolyForm Noncommercial 1.0.0: use it, change it and share it for anything noncommercial. Mystic Forge is a separate project under its own MIT licence. Everything else the gateway is built on is listed in docs/THIRD-PARTY-NOTICES.md.