MCP Playground

What this is

MCP Playground is a browser-managed playground for authoring persistent mock MCP servers and OpenAI-compatible endpoints. It is purpose-built for Microsoft Copilot Studio demos, bootcamps, and solution-architecture training. Admins can model multiple mock servers, multiple endpoints, and shared demo datasets. Definitions and live demo data persist, so trainees can keep working across restarts.

Related MCP server: SimuLoom MCP

Exposed surfaces

flowchart LR
    Trainer["🧑‍🏫 Trainer<br/>browser or AI agent"]
    Attendee["👥 Attendees<br/>Copilot Studio / Cowork"]

    subgraph App["MCP Playground"]
        UI["Admin UI<br/>/ui/"]
        AdminAPI["Admin API<br/>/api/*"]
        AdminMCP["Management MCP<br/>/mcp/_admin — 57 tools"]
        MockMCP["Mock MCP servers<br/>/mcp/{slug}"]
        MockREST["REST mocks + Swagger<br/>/mock/{slug}/*"]
        LLM["OpenAI-compatible<br/>/v1/{slug}/chat/completions"]
        Store[("SQLite on /data<br/>definitions · live · seed")]
    end

    Trainer --> UI --> AdminAPI
    Trainer --> AdminMCP --> AdminAPI
    Attendee --> MockMCP
    Attendee --> MockREST
    Attendee --> LLM

    AdminAPI --> Store
    MockMCP --> Store
    MockREST --> Store
    LLM --> Store

    classDef person fill:#deecf9,stroke:#0078d4,stroke-width:2px,color:#12232e
    classDef admin fill:#e8dff5,stroke:#742774,stroke-width:2px,color:#2b1b2b
    classDef mock fill:#dff6dd,stroke:#107c10,stroke-width:2px,color:#0b2b0b
    classDef data fill:#fff4ce,stroke:#d29200,stroke-width:2px,color:#3b2f00

    class Trainer,Attendee person
    class UI,AdminAPI,AdminMCP admin
    class MockMCP,MockREST,LLM mock
    class Store data

Purple is trainer-only and needs admin auth. Green is what attendees consume. Everything reads and writes the same SQLite file, so a change made through the UI is instantly visible over MCP, REST, and Swagger.

Quick start (local, no container)

uv sync
cp .env.example .env
uv run python main.py
curl http://localhost:2009/health

Expected response:

{"status":"ok"}

Quick start (container)

docker compose up --build

Podman equivalent:

podman compose up --build

Then verify:

curl http://localhost:2009/health

Configuration

Copy .env.example to .env and edit values for your environment.

Admin UI

The admin UI at /ui/ has eleven tabs.

Catalog and bootcamp cloning

The Catalog tab is the first tab in the sidebar. It shows every server in a card grid with slug, auth mode, metrics for datasets, tools, and rows, and an N recipes badge. From a card, an admin can create one clone or bulk-clone one source server into numbered team servers.

This is the bootcamp provisioning path: build one good server, then bulk-clone it once per training team.

Bulk clone is all-or-nothing. If any target slug already exists, it creates nothing. Slugs are numbered with zero padding to the width of start + count - 1, with a minimum width of two: prefix hr-team, count 20, start 1 creates hr-team01 through hr-team20.

Clone deep-copies the server row, datasets, live dataset rows, seed dataset rows, and endpoints with remapped dataset IDs. It does not copy API keys, call log traffic, or LLM endpoints.

Bulk clone deliberately does not clone recipes. A recipe is one assignment that can be used by every team; cloning it once per generated server would create duplicate playbooks that trainers then have to maintain by hand. The public recipe page shows the tools from the template server, and trainers give attendees their team-specific server URL separately.

Recipes

A recipe is an agent playbook: a scenario-level assignment that tells a bootcamp attendee what agent to build. It contains a title, skill badge, department, summary, example prompts, copy-paste agent_instructions, a set of MCP tools, and optional informational destinations such as Outlook or Teams.

Schema version was bumped from 2 to 3 and adds two tables:

Recipes are the deliberate exception to the rest of the schema. Everywhere else server_id is a foreign key. A recipe can span tools from multiple servers, so it is an instance-level object, not a child of one server.

The Recipes tab sits between Catalog and Cohort. It has a recipe list on the left and an editor on the right for slug, title, department, skill, summary, agent instructions, published state, example prompts, server+tool picker, and destination tags. Actions are Save, Delete, Copy public link, Open public page, and Download handout.

Admin API under /api is session-gated:

Public surface:

This is the first unauthenticated HTML surface in the app. It is read-only: no session, no cookie, no POST, and no mutation. Only published = 1 recipes are exposed. A draft or unknown slug returns 404, not 403, so existence is not leaked. The public API never exposes API keys, password hashes, or call_log.

First boot seeds 7 published recipes:

The seed set spans 5 servers, 15 datasets, 42 endpoints, and 40 recipe-to-tool links.

The management MCP server exposes nine recipe tools: list_recipes, get_recipe, create_recipe, update_recipe, delete_recipe, set_recipe_tools, validate_recipes, list_recipe_departments, and get_recipe_handout.

Theme

The UI uses a green brand palette: --brand: #16a34a in light mode and #22c55e in dark mode. The success colour --ok is teal (#0e7490) so success callouts stay distinct from the brand colour.

The header has a sun/moon toggle. The selected theme is stored in localStorage.theme and applied to <html data-theme="...">. If no explicit choice exists, the default follows prefers-color-scheme.

An inline script in <head> applies the theme before first paint, preventing a white flash on reload. @media print forces light tokens so recipe handouts print legibly.

Cohort control panel

The Cohort tab is the third tab in the sidebar. It is the bootcamp control panel for trainers.

Set PUBLIC_BASE_URL before exporting handouts. Cohort URLs are built from PUBLIC_BASE_URL, defaulting to http://localhost:2009. If you leave the default, the handout contains localhost URLs that only work on the trainer's machine.

API keys are global, not per-server. The api_key table has no server_id column. Keys are sha256-hashed and the plaintext is shown exactly once at creation. The handout cannot contain a per-team API key. Servers with auth_mode='none' are handout-ready as-is; servers with auth_mode='api_key' need a key distributed out-of-band.

Multi-table datasets and relationships

Datasets stay flat JSON row collections. A relationship is metadata that links a field on one dataset to a field on another, so callers can inline related rows at query time with the expand query parameter. Relationships are declared per server on the Datasets tab.

Relationships are advisory. They do not enforce foreign keys in SQLite, they do not cascade, and they do not block writes that break a link. A missing parent resolves to null; a childless parent resolves to [].

Rules:

• expand works on read operations only. create, update, and delete with expand return 400.

• Depth is one level. A dotted name such as order.customer returns 400.

• At most 5 expand names per request. Repeats are deduplicated.

• summary_fields projection is preserved; expanded keys are merged on top of it.

• A forward expand returns an object or null. An inverse expand returns an array.

• expand, limit, offset, and _row_id are reserved and cannot be used as expand names.

relation_type is many_to_one or one_to_one. Self-references are allowed. The same six operations are exposed as management MCP tools.

Example: GET /mock/contoso-orders/order-lines?expand=order inlines the parent order into every line. GET /mock/contoso-orders/orders/1001?expand=lines inlines the line array into the order.

Seeded sample servers

First boot seeds 5 servers, 15 datasets, 42 endpoints, 12 relationships, 1 mock LLM endpoint, and 7 published recipes. All five seeded servers use auth_mode='none', so they are handout-ready without a key.

Dataset row totals: contoso-orders has orders 40 / order_lines 120; northwind-hris has employees 30 / time_off_requests 28 / org_units 6; fabrikam-it-service has tickets 30 / assets 18 / service_catalog 8; adatum-crm has accounts 20 / contacts 30 / opportunities 26; contoso-expenses has expense_reports 24 / expense_lines 60 / cost_centres 8 / approvals 24.

Seeded recipes span all 5 servers, all 15 datasets, all 42 endpoints, and 40 recipe-to-tool links. Two recipes are cross-server.

Calling a server over plain REST

Every server is exposed twice from the same endpoint definitions.

The REST surface uses the endpoint's own method and path verbatim.

curl http://localhost:2009/mock/contoso-orders/orders?limit=5
curl http://localhost:2009/mock/contoso-orders/orders/1001
curl "http://localhost:2009/mock/contoso-orders/orders?status=open"
curl "http://localhost:2009/mock/contoso-orders/orders/search?q=northwind"
curl -X POST http://localhost:2009/mock/contoso-orders/orders \
  -H 'content-type: application/json' \
  -d '{"customer":"Fabrikam","status":"open","total":42}'
curl -X DELETE http://localhost:2009/mock/contoso-orders/orders/1001

Query string, JSON body and path placeholders are merged into one flat parameter set. Create returns 201, everything else returns 200.

The Test console in the admin UI calls this surface directly. Pick REST — /mock/{slug} as the surface to exercise writes and see the real HTTP status plus a copyable curl line. The Executor surface is admin-gated and read-only, so it cannot test create, update or delete.

When a server's authentication is set to API key, send the key as X-API-Key: <key> or Authorization: Bearer <key>.

Importing into Power Platform as a custom connector

The Swagger export at /api/servers/{id}/swagger describes this REST surface, so it imports directly as a custom connector.

1. Download the Swagger from the server's Connect it tab.

2. Open Power Apps or Power Automate, go to Custom connectors.

3. Choose New custom connector > Import an OpenAPI file.

4. Add the connector to your agent in Copilot Studio.

See COPILOT-STUDIO.md for the full runbook covering both connection paths — MCP server onboarding and Swagger-based custom connector.

Management MCP server

/mcp/_admin is a second FastMCP server that exposes 57 tools mirroring the admin REST API. It lets an LLM agent drive the entire playground — create servers, clone team servers, load datasets, define endpoints, adjust LLM responses, manage recipes, and inspect traffic — without a human touching the web UI.

Authentication: API key with admin scope, passed as X-API-Key: <key> or Authorization: Bearer <key>.

Everything the browser UI can do is also available as an MCP tool, with exactly three intentional exceptions: POST /api/auth/login, POST /api/auth/logout, and GET /api/auth/me. Those are browser-session-cookie endpoints and are meaningless over MCP, which has its own API key auth. tests/test_mcp_parity.py enforces this parity automatically so it cannot silently drift.

Setup

You need an API key with admin scope. Create one in the UI (API keys tab) or over the API.

1. Log in and create a key

BASE=http://localhost:2009        # or https://<your-fqdn>

curl -s -c /tmp/pg.jar -X POST "$BASE/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<your-admin-password>"}'

curl -s -b /tmp/pg.jar -X POST "$BASE/api/keys" \
  -H 'Content-Type: application/json' \
  -d '{"label":"admin-mcp","scope":"admin"}'

The response contains the plaintext key exactly once. Copy it now — only a hash is stored. scope is admin (read + write) or readonly.

2. Verify the key works

curl -s -o /dev/null -w '%{http_code}\n' -X POST "$BASE/mcp/_admin" \
  -H "X-API-Key: <your-key>" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

200 means you are in. 401 means the key is missing, wrong, or lacks admin scope. 406 means the Accept header is missing text/event-stream.

3. Point an MCP client at it

{
  "mcpServers": {
    "playground-admin": {
      "url": "https://<your-fqdn>/mcp/_admin",
      "headers": { "X-API-Key": "<your-key>" }
    }
  }
}

flowchart LR
    Agent["🤖 AI agent<br/>MCP client"]
    Key{{"API key<br/>scope: admin"}}
    Admin["/mcp/_admin<br/>57 tools"]
    Work["Create servers · clone for teams<br/>load datasets · define endpoints<br/>manage recipes · inspect traffic"]

    Agent -->|"X-API-Key header"| Key
    Key -->|"401 if missing or readonly"| Admin
    Admin --> Work

    classDef person fill:#deecf9,stroke:#0078d4,stroke-width:2px,color:#12232e
    classDef gate fill:#fde7e9,stroke:#a4262c,stroke-width:2px,color:#3b1114
    classDef admin fill:#e8dff5,stroke:#742774,stroke-width:2px,color:#2b1b2b
    classDef mock fill:#dff6dd,stroke:#107c10,stroke-width:2px,color:#0b2b0b

    class Agent person
    class Key gate
    class Admin admin
    class Work mock

Because every UI action has a tool equivalent, an agent can provision an entire bootcamp end to end: clone one source server into 20 team servers, seed their data, mint per-team API keys, and export the handouts — without opening the browser.

Tools are grouped into nine areas:

reset_all_to_seed requires confirm=true. Without it, the tool returns {"ok": false, "error": "set confirm=true to proceed", "would_affect": "..."} and changes nothing.

list_api_keys returns key metadata only and never exposes a secret hash. create_api_key returns the plaintext key exactly once; copy it immediately because it cannot be retrieved again. delete_api_key is destructive and requires confirm=true.

export_swagger returns the server's Swagger/OpenAPI spec and accepts an optional base_url override. export_server returns a portable JSON bundle for one server. import_server imports that bundle and can override the imported slug.

validate_recipes reports recipe issues, list_recipe_departments returns department counts, get_recipe_handout renders one recipe as Markdown, and list_expands lists the available $expand paths for a dataset.

Data & persistence

MCP Playground has three data tiers.

Definitions are the authored servers, endpoints, datasets, relationships, and recipes. They persist forever until an admin changes them.

Live data is the mutable runtime state used during a demo. It persists across restarts and is mutated by agent calls. If an agent creates an order during a demo, that order is still there tomorrow.

Seed data is an immutable snapshot. Reset to seed restores live data back to the snapshot. Save as seed promotes the current live data into the snapshot.

flowchart LR
    Def["📐 Definitions<br/>servers · endpoints · datasets<br/>relationships · recipes"]
    Live["🔄 Live data<br/>mutable demo rows"]
    Seed["📦 Seed data<br/>immutable snapshot"]

    Def -.->|"shape the rows"| Live
    Live -->|"Save as seed"| Seed
    Seed -->|"Reset to seed"| Live
    Agents["🤖 Agent calls during a demo"] -->|"create · update · delete"| Live

    classDef def fill:#deecf9,stroke:#0078d4,stroke-width:2px,color:#12232e
    classDef live fill:#dff6dd,stroke:#107c10,stroke-width:2px,color:#0b2b0b
    classDef seed fill:#fff4ce,stroke:#d29200,stroke-width:2px,color:#3b2f00
    classDef ext fill:#f3f2f1,stroke:#605e5c,stroke-width:2px,color:#201f1e

    class Def def
    class Live live
    class Seed seed
    class Agents ext

All three tiers live in the same SQLite file and survive restarts. If an agent creates an order during a demo, that order is still there tomorrow — until someone resets to seed.

The Compose setup uses the named Docker volume playground-data mounted at /data. That is what keeps SQLite data alive across docker compose restart, docker compose down, and later docker compose up. Deleting that volume wipes all definitions, live data, and seed data.

Deployment

Two supported targets.

Local container — the quick-start path above: docker compose up --build (or podman compose up --build) exposes the app on port 2009 and persists SQLite in the playground-data volume.

Azure Container Apps — scale-to-zero, under €1/month, HTTPS with a stable FQDN. Full runbook in AZURE.md.

flowchart LR
    Dev["💻 Local dev<br/>uv run · compose"]
    GH["GitHub<br/>Roelzz/mcp_playground"]
    Actions["GitHub Actions<br/>build-image.yml"]
    GHCR["ghcr.io<br/>public image"]
    Deploy["deploy.sh<br/>Bicep · one resource group"]
    ACA["Azure Container Apps<br/>min=0 max=1 · managed TLS"]
    Files[("Azure Files<br/>/data · SQLite")]

    Dev -->|"git push"| GH --> Actions --> GHCR
    Dev -->|"az login"| Deploy --> ACA
    GHCR -->|"image pull"| ACA
    ACA -->|"SMB mount"| Files

    classDef local fill:#deecf9,stroke:#0078d4,stroke-width:2px,color:#12232e
    classDef ci fill:#f3f2f1,stroke:#605e5c,stroke-width:2px,color:#201f1e
    classDef azure fill:#e8dff5,stroke:#742774,stroke-width:2px,color:#2b1b2b
    classDef data fill:#fff4ce,stroke:#d29200,stroke-width:2px,color:#3b2f00

    class Dev local
    class GH,Actions,GHCR ci
    class Deploy,ACA azure
    class Files data

Short version, assuming az login is done and infra/main.parameters.json is filled in:

BOOTSTRAP_PASSWORD='<pick-a-strong-password>' ./deploy.sh

Takes about three to four minutes and prints the FQDN when it finishes. Read AZURE.md first — two env vars (SQLITE_JOURNAL_MODE=DELETE and SQLITE_VFS=unix-dotfile) are mandatory on Azure Files, and teardown.sh permanently changes the URL.

Development

uv run pytest -q
uv run ruff check .
uv run ruff format .

Network note: blocked PyPI downloads

The project uses the public PyPI index. On some corporate networks — including any machine behind Microsoft Entra Global Secure Access — files.pythonhosted.org is blocked by web filtering, so pypi.org resolves but package downloads fail. The block applies inside containers too.

If you hit that, redirect UV to a mirror locally — never commit the mirror as project config.

Host-side dependency resolution (uv lock):

export UV_DEFAULT_INDEX=https://<your-mirror>/simple

Container build. uv sync --frozen uses the absolute artefact URLs recorded in uv.lock, so UV_DEFAULT_INDEX alone is not enough — rewrite the lock, build, restore:

sed -i '' -e 's|https://files.pythonhosted.org/packages|https://<your-mirror>/packages|g' \
          -e 's|https://pypi.org/simple|https://<your-mirror>/simple|g' uv.lock
podman build -t mcp-playground .
git checkout uv.lock

uv.lock records sha256 hashes alongside every URL. A mirror that copies the pythonhosted path layout serves identical artefacts, so the hashes still verify and the rewrite is safe.

For a production or Microsoft-shop deployment, use an Azure Artifacts feed with a PyPI upstream instead of a public mirror.

Roadmap

Azure deployment shipped — see AZURE.md. Nothing is currently blocking a bootcamp.

Untested rather than broken, worth knowing before a large session:

• No load test against a full 200-attendee cohort yet.

• SQLite lock behaviour after a hard container kill (not a graceful restart) is unverified.