Backlot

A read-only mock server that stands in for a whole stack of enterprise SaaS knowledge sources
at once.
It speaks each service's real read API — the exact response shapes, pagination schemes, auth,
and native permission endpoints their official SDKs expect — over a corpus you supply, so a
RAG/search connector built on those SDKs can be exercised end-to-end without the live
services.

Quickstart

pip install backlot

That puts the backlot command on PATH. A server needs a corpus, and one is bundled with the
package — 136 documents covering every source it serves — so there is nothing to fetch or write:

backlot import --bundled    # the bundled corpus -> data/mock.sqlite + data/tokens.yaml
backlot serve               # http://127.0.0.1:8000
curl -s localhost:8000/health

Or skip the CLI entirely and let a test spin one up on a free port, serving that same corpus
(pip install "backlot[examples]" for the vendor SDKs the first snippet uses):

import backlot
from slack_sdk import WebClient

with backlot.mock_server() as m:                       # no arguments: the bundled corpus
    slack = WebClient(token=m.token, base_url=f"{m.base_url}/slack/api/")
    print(slack.conversations_list()["channels"])

with backlot.mock_server(records=[                     # or your own records, inline
    {"source_type": "confluence", "space": "handbook", "title": "On-call",
     "content": "Page for Sev1 and Sev2 only.", "author_email": "[email protected]"},
]) as m:
    ...

python -m backlot is the same CLI as the backlot script, for when the venv is not activated.
Working on Backlot itself instead of with it? CONTRIBUTING.md covers the
from-source install.

Docker

docker build -t backlot .                  # server + the bundled corpus baked in; no download
docker run -p 8000:8000 backlot
curl -s localhost:8000/health

That image answers every endpoint of every source out of the box. Use
--target serve for a server with no corpus, for a deployment that mounts its own
/app/data.

Why you need this

Connectors are easy to write and hard to trust. Proving one works means an account with every
vendor, an OAuth app per vendor, seeded data in each, and rate limits between you and every retry —
so most of it
gets tested against fixtures that agree with your assumptions instead of with the API. Backlot is
the API: same shapes, same pagination, same permission endpoints, over documents you control.

It is the right tool when you are:

• building or upgrading a connector — crawl a source to exhaustion, then diff what you got
  against what you loaded, on a corpus small enough to reason about
• testing ACL-scoped retrieval — every document carries its own readers, and each user's token
  sees only theirs, so "does this leak" is a test rather than an audit
• running that suite in CI — no accounts, no secrets, no network, no flakes from someone else's
  outage; a server starts in a second and dies with the test
• evaluating RAG or agents — point an SDK, an MCP server, or a LlamaIndex reader at it and get
  the same answers on every run, because ids and timestamps are derived, not random
• reproducing a bug you cannot reach — a paginated edge case, an odd MIME type, an empty thread:
  write the document that causes it and serve it in seconds

It is not a sandbox for writes, a rate-limit or latency simulator, or a source of realistic
content — the documents are yours.

Preparing a corpus

The server reads a corpus from data/ (mock.sqlite + tokens.yaml). Build it from your own
documents, or load a public dataset.

You describe each document the way its own service would, and a per-source JSON Schema says what
that record may carry. title and content are served verbatim; so is every other field you set —
authors, timestamps, threads, comments, labels, states, ACLs — so no part of a response has to be
synthesized. What you leave out is filled in deterministically, each value hashed from the
stable key it belongs to (a document's doc_id, a container's name, an author's address), so ids
never move between calls or pages.

Bring your own corpus

One JSONL document per line, validated against a per-service JSON Schema
(backlot/schemas/), then loaded:

backlot import mycorpus.jsonl              # validate + load -> data/
backlot import mycorpus.jsonl --dry-run    # validate only, no DB writes
backlot import mycorpus.jsonl --roster roster.yaml   # state the principals, don't derive them
backlot import corpus.jsonl.gz             # gzipped, read as a stream
backlot import artifact-dir/               # a sharded corpus + its manifest, digests verified

{"source_type": "slack", "channel": "incidents", "author_email": "[email protected]", "created": "2026-02-10T18:00:00Z", "content": "Anyone seeing 502s from the gateway?", "replies": [{"content": "Looking now.", "author_email": "[email protected]", "created": "2026-02-10T18:00:40Z"}]}
{"source_type": "gmail", "mailbox": "ceo", "title": "Q1 board deck draft", "content": "Draft narrative for the Q1 board meeting.", "author_email": "[email protected]", "created": "2026-01-20T16:00:00Z", "to": "[email protected]", "readers": ["[email protected]", "[email protected]"]}

A record states the facts the served document cannot exist without — who wrote it, where it
lives, when it happened — plus whatever its own vendor always reports. Nothing is filled in behind
your back: backlot import --dry-run names every record that leaves one out. Where to look next:

The schemas double as the contract for LLM dataset generation: hand one to a model as a
structured-output schema, generate records, then --dry-run before loading. See
backlot/schemas/README.md.

Load a public dataset

EnterpriseRAG-Bench is ~500k synthetic
enterprise documents across nine of the supported sources. One command downloads, loads and
ACL-derives it:

backlot import --type enterpriserag-bench

What that dataset does and does not carry, and how to redistribute it as BYO-JSONL, is in
examples/import-enterpriserag-bench/ — it is one corpus
you can load, not part of this server's contract.

Auth & tokens

Each service authenticates its own way, and the mock expects what the real one does: a bearer token
for most, HTTP Basic for Jira/Confluence, a bare Authorization value for Linear's personal API
keys, SigV4 for S3, and Google's OAuth token exchange for a connector carrying a client config.

You construct none of it. Two mock-only endpoints hand out every credential the corpus generated —
an admin/service token that bypasses the ACL (use it to crawl), plus one identity per person, each
seeing only what their own ACL permits:

curl -s localhost:8000/_mock/users

{ "org": "acme", "admin_token": "admin-service-token", "count": 10,
  "admin_s3_access_key_id": "AKIA732S…", "admin_s3_secret_access_key": "l4sz5sXT…",
  "users": [{ "email": "[email protected]", "name": "Ava Chen", "token": "usr-29b84da570…",
              "s3_access_key_id": "AKIADNLO…", "s3_secret_access_key": "0FdhlUUQ…",
              "groups": ["engineering", "handbook", "product", "design"] }] }

curl -s localhost:8000/_mock/credentials    # for a Google client that wants a config, not a token

{ "org": "acme", "token_uri": "http://localhost:8000/oauth2/token",
  "oauth_client": { "client_id": "e8ae7a….apps.googleusercontent.com", "client_secret": "GOCSPX-…" },
  "service_account": { "type": "service_account", "client_email": "…", "private_key": "…" } }

Use a user's token and every API filters to that user, which is what makes per-user access a test
rather than an audit. token_uri points back at the mock, so a client library's own refresh lands
here and resolves to the same ACL — a user's refresh_token is just their bearer token. Both
endpoints serve credentials in the clear, so BACKLOT_EXPOSE_TOKENS=false closes them; the same
values are in data/tokens.yaml. Per-service detail:
examples/using-official-sdk/.

Example Usages

Every one of these points a real client at the mock's base URL — that is the only change from
talking to the live service.

Official SDKs

from slack_sdk import WebClient
WebClient(token=TOKEN, base_url="http://localhost:8000/slack/api/")

from github import Github, Auth
Github(auth=Auth.Token(TOKEN), base_url="http://localhost:8000/github")

from atlassian import Jira, Confluence
Jira(url="http://localhost:8000/atlassian", username="svc@x", password=TOKEN)
Confluence(url="http://localhost:8000/atlassian/wiki", username="svc@x", password=TOKEN)

from googleapiclient.discovery import build
from google.api_core.client_options import ClientOptions
from google.oauth2.credentials import Credentials
creds = Credentials(token=TOKEN)
build("gmail", "v1", credentials=creds, client_options=ClientOptions(api_endpoint="http://localhost:8000"))
build("drive", "v3", credentials=creds, client_options=ClientOptions(api_endpoint="http://localhost:8000/drive/v3"))

from notion_client import Client
Client(auth=TOKEN, base_url="http://localhost:8000/notion")   # SDK appends /v1/ itself

import boto3
from botocore.config import Config
boto3.client("s3", endpoint_url="http://localhost:8000/s3", aws_access_key_id=AK, aws_secret_access_key=SK,
             region_name="us-east-1", config=Config(s3={"addressing_style": "path"}))

A runnable, self-contained script per service is in examples/using-official-sdk/.

MCP

An MCP server pointed at the mock retrieves through it, ACL-scoped to whatever token it
authenticates with. Some vendors publish a server that takes a base URL — use it directly:

# examples/using-mcp-with-agents/atlassian.py — the community-official mcp-atlassian, over Docker.
# The host must end in .atlassian.net for the server's Cloud detection, so alias it at the mock.
params = StdioServerParameters(command="docker", args=[
    "run", "-i", "--rm", "--add-host=mock.atlassian.net:host-gateway",
    "-e", "JIRA_URL=http://mock.atlassian.net:8000/atlassian",
    "-e", "CONFLUENCE_URL=http://mock.atlassian.net:8000/atlassian/wiki",
    "-e", "[email protected]", "-e", "[email protected]",
    "-e", f"JIRA_API_TOKEN={token}", "-e", f"CONFLUENCE_API_TOKEN={token}",  # a user token -> its ACL
    "-e", "MCP_ALLOWED_URL_DOMAINS=atlassian.net", "-e", "READ_ONLY_MODE=true",
    "ghcr.io/sooperset/mcp-atlassian:latest", "--transport", "stdio",
])

For the ones that don't — GitHub, Slack, Gmail, Drive, HubSpot — a generic OpenAPI→MCP bridge
turns the mock's own typed /openapi.json into tools instead (GET /_mock/openapi/<source> serves
the per-source slice):

# examples/using-mcp-with-agents/github.py — no vendor SDK, no vendor MCP server
params = StdioServerParameters(command=sys.executable, args=[
    "examples/using-mcp-with-agents/_openapi_bridge.py",
    "--source", "github", "--base-url", mock.base_url, "--token", mock.token,
])

And for the two sources with no REST surface at all — Linear and Fireflies, which are GraphQL-only —
a GraphQL→MCP bridge reads the endpoint's own introspection and turns each root Query field
into a typed tool, arguments and selection set derived from the schema:

# examples/using-mcp-with-agents/linear.py — GraphQL-only, so /openapi.json describes nothing
params = StdioServerParameters(command=sys.executable, args=[
    "examples/using-mcp-with-agents/_graphql_bridge.py",
    "--source", "linear", "--base-url", mock.base_url, "--token", mock.token, "--depth", "1",
])

Any of the three ways, an agent then calls session.list_tools() and retrieves. Runnable agents for both LLM backends (Anthropic + OpenAI), one file per service, are in examples/using-mcp-with-agents/.

LlamaIndex readers

Point official LlamaIndex readers
(llama-index-readers-*) at the mock and load an enterprise corpus as Document objects — the
first step of a LlamaIndex ingestion/RAG pipeline.

from llama_index.readers.github import GitHubIssuesClient
GitHubIssuesClient(github_token=TOKEN, base_url="http://localhost:8000/github")

from llama_index.readers.confluence import ConfluenceReader
ConfluenceReader(base_url="http://localhost:8000/atlassian/wiki", cloud=False, api_token=TOKEN)

One runnable script per source is in examples/using-llamaindex-readers/.

Mirage

mirage mounts a SaaS backend as a virtual
filesystem an agent reads with shell commands (ls, cat, grep, find). Point its resources at the mock and you can drive a mirage agent over your corpus offline.

from mirage import MountMode, Workspace
from mirage.resource.slack import SlackConfig, SlackResource

resource = SlackResource(SlackConfig(token=TOKEN, base_url="http://localhost:8000/slack/api"))
ws = Workspace({"/slack": resource}, mode=MountMode.READ)
await ws.execute("ls /slack/channels/")        # then cat a channel's dated chat.jsonl

One runnable script per source plus a unified.py that greps
across Slack/Gmail/Google Drive at once are in examples/using-mirage/.

Endpoints (read-only)

Mock-only endpoints: /health, /_mock/users, /_mock/credentials, /_mock/openapi/<source>,
/openapi.json.

Tests

pytest              # unit (synth/pagination/acl/schema/importer parsers) + HTTP endpoint tests
                    # (full-crawl completeness, content round-trip, ACL enforcement)
ruff check . && ruff format --check .

Configuration

Every setting is an env var with a BACKLOT_ prefix, and a .env file in the working directory is
read too. Defaults are what the server uses when the var is unset.

Contributing

See CONTRIBUTING.md. The short version: fidelity to the real APIs is the point,
so a divergence is a bug — measure against the real service, and bring a test that fails without
your fix.

License

MIT