SQLite MCP Sidecar

プロジェクトについて

アプリケーションが SQLite ファイルを所有しています。エージェントにそのファイルを読み取らせ、場合によっては数行を変更させたいとします。 エージェントに SQL 接続を渡すとファイル全体へのアクセスを許してしまい、誤った条件で実行した 1 つの DELETE からは復旧できません。sqlite-sidecar-mcp はそのアプリケーションの隣で、もう 1 つの SQLite クライアントとして動作し、 HTTP 経由で MCP を提供します。所有元のアプリケーションを変更する必要はありません。

本番環境では MCP Canary API の隣で動作し、運用担当者のコーディングエージェントにライブデータベースへの読み取り専用アクセスを提供します。

flowchart TD
    agent[AI / MCP client] -->|HTTPS| proxy[Reverse proxy]
    proxy -->|private HTTP| sidecar[sqlite-sidecar-mcp]
    sidecar -->|SQLite client| db[(app.db)]
    app[Owning application] -->|SQLite client| db

この製品は 2 種類の呼び出し元から保護します。1 つは認可されていないクライアントで、トークンとリクエスト予算によって遮断します。もう 1 つは認可されているものの、誤操作をするクライアントです。ここが一般的なケースとは異なります。書き込み権限を持つエージェントでも、誤った内容を書き込むことがあります。そのような事態に備えて、構造化された書き込み、必須の条件、カスケードも数える行数制限、1 分あたりの書き込み予算を設けています。

重要

**1 つのサイドカープロセスが提供するデータベースは 1 つです。**リクエスト予算、書き込み予算、冪等性キャッシュはプロセスメモリ上に保持されます。2 つ目のレプリカを稼働させると、独立した予算と独立したキャッシュが 2 つでき、問題を知らせるものは何もありません。このサービスをスケールさせないでください。2 つ目のサイドカーは、別のデータベースまたは別の信頼境界に対してのみ実行してください。

使用技術

• .NET 10、ASP.NET Core
• Streamable HTTP 経由の Model Context Protocol
• バンドルされたネイティブ SQLite を使用する Microsoft.Data.Sqlite
• 行の出力に TOON を使用。JSON よりトークン消費量を抑えられます

(先頭に戻る)

はじめに

前提条件

• Docker
• すでに存在する SQLite データベース。サイドカーがデータベースを作成することはありません。作成すると誤ったパスが隠れ、本物のデータベースの隣に空のデータベースが残ってしまうためです。

実行する

docker run -d --name sqlite-sidecar \
  -p 127.0.0.1:8080:8080 \
  -v /srv/myapp/data:/data \
  -e SQLITE_SIDECAR_DB=/data/app.db \
  -e SQLITE_SIDECAR_TOKEN='<a long random string>' \
  -e SQLITE_SIDECAR_PERMISSIONS=schema,read \
  --read-only --tmpfs /tmp \
  --cap-drop=ALL --security-opt=no-new-privileges \
  ghcr.io/xakpc/sqlite-mcp-sidecar:latest

読み取り専用の権限セットを使用する場合も、マウントは書き込み可能でなければなりません。SQLite は WAL データベースへの読み取り専用接続でも -shm ファイルを読み書き可能な状態で開くため、読み取り専用マウントでは、設定ミスではなく権限の問題のように見える形で失敗します。

エージェントを接続する

エンドポイントは /db/mcp で、トークンは Authorization ヘッダーに設定します。

{
  "mcpServers": {
    "app-database": {
      "url": "https://example.com/db/mcp",
      "headers": { "Authorization": "Bearer <the token>" }
    }
  }
}

OAuth はありません。OAuth ディスカバリーを必須とするクライアントは、401 応答でリソースメタデータを見つけられず停止します。想定している利用者は、運用担当者が静的ヘッダーを設定した 1 つのエージェントです。

トークンと環境変数ブロックを生成する

dotnet run scripts/token.cs

デプロイ形態を尋ね、暗号学的に安全な乱数ソースからトークンを生成し、起動に失敗する権限セットを修正して、.env、シェル、または compose 形式でブロックを出力します。

(先頭に戻る)

利用できるツールは、権限セットによって決まります。デプロイ環境でサポートされていないツールは tools/list に含まれません。表示されてから失敗することはありません。

query は、コンパクトな表形式テキストである TOON で応答します。

rows[2]{id,status}:
  54,done
  41,failed

truncated: false

truncated: true は、制限によって読み取りが停止したことを意味し、クエリが失敗したという意味ではありません。

構造化された書き込み

update と delete は、SQL ではなくフラットなフィルターを受け取ります。各条件は AND で結合されます。or や入れ子には対応していません。選言の場合は分岐ごとに 1 回呼び出してください。これにより、より厳密な上限が適用されます。各呼び出しは個別に事前カウントされ、制限されます。一方、1 回の or 呼び出しでは、すべての分岐の影響範囲が単一の maxRows にまとめられてしまいます。

maxRows は、書き込みによって変更される すべての 行を数えます。ON DELETE CASCADE で削除された行や、トリガーによって書き込まれた行も含まれます。maxRows: 1 を指定した delete が、カスケード先のツリー全体をひそかに破棄して 1 行と報告することはありません。フィルターに一致する行が多すぎる場合は書き込みの開始前に拒否され、実際の書き込みが上限を超えることが判明した場合はロールバックされます。

すべての書き込みツールには、必須の requestId があります。同じ requestId を指定すると、書き込みを二重に適用する代わりに、コミット済みの書き込みに対する保存済みの応答が返されます。失敗はキャッシュされないため、失敗後の再試行は実際に再試行されます。

（先頭に戻る）

1つのデプロイメントには、1つのトークンと1つの権限セットがあります。権限はデプロイメントのプロパティであり、ユーザーのプロパティではありません。ユーザー、ロール、ACLはありません。信頼レベルごとに別々のデプロイメントを使用することで、デプロイメント設定上で境界を明確にできます。

SQLITE_SIDECAR_PERMISSIONS=schema,read      # the default

danger-raw-write という名前は、意図的に危険性を強調しています。中立的な名前では、その代償が見えなくなってしまいます。

警告

権限はデータベース内のすべてのテーブルに適用されます。 テーブルの許可リストも、列の許可リストもありません。write を持つエージェントから、特定のテーブルを保護することはできません。変更されたくないテーブルは、別のサイドカーを使う別のデータベースに配置する必要があります。

サイドカーは起動時に次の2つのルールを適用します。そのため、設定ミスがあれば後で思いがけず発覚するのではなく、起動に失敗します。

• 読み取りの最低要件。 write と danger-raw-write は、schema と read を併せて設定した場合にのみ有効です。構造化された書き込みでは、稼働中のスキーマに照らして名前を検証するため、schema を呼び出せないエージェントは推測することになります。不足している権限が黙って追加されることはありません。追加されると、SQLITE_SIDECAR_PERMISSIONS がデプロイメントの実態を示さなくなるためです。
• 未知の名前は許可しません。 SQLITE_SIDECAR_PERMISSIONS=reed の場合、オペレーターが想定するより少ない権限を黙って付与するのではなく、起動に失敗します。

どの権限も、別の権限を付与しません。read に write は含まれず、danger-raw-write は write とは独立しています。

（先頭に戻る）

設定

すべての値は SQLITE_SIDECAR_ プレフィックスを持つ環境変数です。値が未設定または無効の場合、起動に失敗し、問題をすべてまとめて報告します。サイドカーが機能を制限した状態で起動することはありません。

必須：

/health はプロセスが稼働していることだけを報告します。データベースには一切アクセスしません。プローブは数秒ごとに実行されるため、コストの高いプローブは、稼働中のアプリケーションに対するサービス拒否攻撃の手段になりかねません。ファイルが必要なチェックは起動時に一度だけ実行します。

（トップに戻る）

デプロイ

注意

プロキシで /db プレフィックスを削除してはいけません。 /db/mcp が公開パス全体です。サイドカーはエージェントが呼び出すものと同じ URL にルーティングします。Kamal と Coolify はどちらも、マッチしたプレフィックスをデフォルトで削除するため、プレフィックスが削除されると、サーバーが壊れているように見える 404 が発生します。以下のすべての設定例では、プレフィックスの削除を無効にしています。

どの方法でも共通する要件は、レプリカを1つにすること、schema,read の場合でも /data を書き込み可能にすること、コンテナのポートをインターネットに公開しないことです。外部からの接続にはリバースプロキシだけを使い、Host ヘッダーの照合もリバースプロキシが行います。サイドカー自体はホストのフィルタリングを行いません。

services:

  app:
    image: my-app
    volumes:
      - sqlite-data:/data

  sqlite-sidecar:
    image: ghcr.io/xakpc/sqlite-mcp-sidecar:latest
    deploy:
      replicas: 1
    environment:
      SQLITE_SIDECAR_DB: /data/app.db
      SQLITE_SIDECAR_TOKEN: ${SQLITE_SIDECAR_TOKEN}
      SQLITE_SIDECAR_PERMISSIONS: schema,read,write,backup
      SQLITE_SIDECAR_BACKUP_DIR: /backups
      ASPNETCORE_URLS: http://0.0.0.0:8080
    volumes:
      - sqlite-data:/data
      - sqlite-backups:/backups
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true

volumes:
  sqlite-data:
  sqlite-backups:

service: sqlite-sidecar
image: ghcr.io/xakpc/sqlite-mcp-sidecar
servers:
  app:
    hosts: [<host that holds the database>]
    proxy:
      ssl: true
      host: <the public host name>
      path_prefix: /db
      strip_path_prefix: false
      app_port: 8080
      healthcheck:
        path: /health
volumes:
  - "<host data directory>:/data"
env:
  clear:
    SQLITE_SIDECAR_DB: /data/app.db
    SQLITE_SIDECAR_PERMISSIONS: schema,read
  secret:
    - SQLITE_SIDECAR_TOKEN

Domain            https://mcp.<domain>
Strip Prefixes    off
Health check      /health
Replicas          1
Volume            <host data directory>:/data, writable

# /etc/systemd/system/sqlite-sidecar.service
[Unit]
Description=sqlite-sidecar-mcp
After=docker.service
Requires=docker.service

[Service]
Restart=always
RestartSec=5
ExecStartPre=-/usr/bin/docker rm -f sqlite-sidecar
ExecStart=/usr/bin/docker run --rm --name sqlite-sidecar \
  -p 127.0.0.1:8080:8080 \
  -v /srv/myapp/data:/data \
  --env-file /etc/sqlite-sidecar.env \
  --read-only --tmpfs /tmp \
  --cap-drop=ALL --security-opt=no-new-privileges \
  ghcr.io/xakpc/sqlite-mcp-sidecar:latest
ExecStop=/usr/bin/docker stop sqlite-sidecar

[Install]
WantedBy=multi-user.target

app = "myapp"

[build]
  image = "ghcr.io/xakpc/sqlite-mcp-sidecar:latest"

[env]
  SQLITE_SIDECAR_DB = "/data/app.db"
  SQLITE_SIDECAR_PERMISSIONS = "schema,read"
  ASPNETCORE_URLS = "http://0.0.0.0:8080"

[[mounts]]
  source = "app_data"
  destination = "/data"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = false
  auto_start_machines = false
  min_machines_running = 1

[[http_service.checks]]
  path = "/health"

fly secrets set SQLITE_SIDECAR_TOKEN='<the token>'

トークンのローテーション

デプロイごとにトークンは1つです。有効期限はなく、サイドカーは別のトークン値を受け付けません。ローテーションではシークレットを変更して再起動するため、その時点ですべてのクライアントが停止します。ここではそれを許容しています。ローテーション期間を設けるには有効なトークンのリストが必要となり、別の製品になってしまうためです。

（トップに戻る）

セキュリティ

すべてのリクエストは、すべてのレイヤーを順番に通過します。機能フラグで無効にできるレイヤーはありません。

flowchart TD
    req[MCP request] --> budget[Request budget]
    budget --> auth[Bearer token check]
    auth --> perm[Deployment permission check]
    perm --> conc[Concurrency semaphore]
    conc --> agent[Agent protections]
    agent --> sandbox[SQLite sandbox]
    sandbox --> sqlite[(app.db)]

    budget -->|fail| e0[429 Too Many Requests]
    auth -->|fail| e1[Unauthorized]
    perm -->|fail| e2[PermissionDenied]
    agent -->|fail| e3[WriteLimitExceeded / WriteBudgetExceeded]
    sandbox -->|fail| e4[QueryRejected]

保証されること

デフォルト設定では、以下が成り立ちます。

• リモートアクセスには認証が必要です。
• デフォルトの権限は読み取り専用です。
• read は write を意味しません。
• schema と read がなければ、write 権限は有効になりません。
• write は、呼び出し元が指定する書き込み SQL を受け付けません。
• 構造化された update と delete には述語が必要で、述語は AND のみで結合されます。
• 構造化された update と delete には厳格な行数上限があり、広範なフィルターは書き込み開始前に拒否されます。
• この行数上限では、書き込みによって変更されるすべての行がカウントされるため、削除行数を 1 行と報告しながら、制限のないカスケードの部分木を削除することはできません。
• 同じ requestId を使った書き込みの繰り返しは、1 回だけ適用されます。
• 構造化された書き込みの繰り返しには、レート制限が適用されます。
• raw 書き込みには、危険性を明示した権限が必要です。
• raw 書き込みでは、DDL、ATTACH、ネイティブ拡張の読み込みを実行できません。
• 呼び出し元はバックアップのファイルシステムパスを指定できません。
• 完全なバックアップファイルは、常に完全なデータベースです。不完全なコピーには .partial サフィックスが付きます。
• クエリには、実行時間、結果数、同時実行数の各上限があります。
• ネイティブ SQLite の防御機能が有効になっています。
• データベースファイルがネットワークを経由することはありません。

これらは具体的な制御です。ネットワークに公開されたデータベースを絶対に安全にするものではありません。

SQLite サンドボックス

最も内側のレイヤーは常に有効で、どの権限でもその一部を無効にすることはできません。danger-raw-write も例外ではありません。文字列マッチングで SQL を検査するのではなく、ネイティブの SQLite オーソライザーを使うため、あらゆる経路で文の準備時に次の操作が拒否されます。

ATTACH            DDL (CREATE / ALTER / DROP)      PRAGMA
load_extension    VACUUM                           transaction control
more than one statement in one request

防御モードが有効になり、信頼できるスキーマが無効になります。接続ごとのランタイム上限によって、SQL の長さ、式の深さ、VDBE 操作数が制限されます。また、実行中の文がタイムアウトを超えると、単に放棄されるのではなく、SQLite 内で中断されます。接続プーリングは無効です。プールされたハンドルでは、前の操作のオーソライザーと上限が保持されるためです。

保証されないこと

注意

元に戻すことはできません。 設定された上限内の delete はコミットされ、復元用のツールはありません。バックアップ戦略の責任は運用担当者にあります。上限が防ぐのは、1 つのミスが対象とする行数、つまり範囲です。誤りは防ぎません。正しく見える書き込みでも、値が間違っていれば、依頼どおりにそのまま適用されます。

danger-raw-write は、その名前が示すとおりの意味です。 運用担当者がこれを有効にすると、トークンを持つユーザーは次の操作を実行できます。

DELETE FROM jobs;

これは想定された動作であり、欠陥ではありません。この権限は、構造化された書き込み、述語の必須指定、maxRows の必須指定、上限付きの事前カウント、変更総数の上限、サーバー生成 SQL という 6 つの保護を意図的に取り除きます。維持される保護は、冪等性キーと書き込み予算の 2 つだけです。上記の SQLite サンドボックスには影響しないため、raw 書き込みでも DDL、データベースのアタッチ、拡張機能の読み込み、内部の sqlite_% オブジェクトへの書き込みはできません。

権限はデータベース全体に適用されます。 権限を参照してください。

トークンを盗んだ者は、デプロイ環境に付与された機能をそのまま使えます。 サイドカーは、機能と影響範囲を制限します。意図的に付与された破壊的な権限を無害にはできません。有効期限も失効リストもありません。失効させるには、シークレットを変更して再起動する必要があります。

予算は処理を抑制しますが、分離はしません。 SQLITE_SIDECAR_MAX_REQUESTS_PER_MINUTE はプロセス全体で共有される固定ウィンドウで、呼び出し元ごとの区分はありません。また、認証前に適用されます。そのため、誤ったトークンによる大量アクセスも抑制され、拒否されたリクエストでも許可枠を消費します。1 つのエージェントが予算を使い切ると、他のエージェントも停止します。書き込み予算も同様に動作します。どちらもプロセスのメモリ上に保持されるため、再起動するとリセットされ、複数のプロセス間で共有されることもありません。

コンテナーのポートをインターネットに直接公開してはいけません。 外部からの唯一の経路はリバースプロキシであり、TLS を終端し、ホスト側のゲートとして機能します。サイドカー自体はホスト側のフィルタリングを行いません。

脆弱性の報告

このリポジトリの GitHub の非公開セキュリティアドバイザリーを利用してください。セキュリティ報告を公開 Issue として作成しないでください。

(トップに戻る)

コントリビュート

コントリビュートを歓迎します。リポジトリをフォークし、ブランチを作成して、プルリクエストを開いてください。

dotnet test --solution Xakpc.SQLiteMCPSidecar.slnx    # the whole suite

pwsh ./scripts/seed-dev-db.ps1                        # one time, before the first launch
pwsh ./scripts/dev-sidecar.ps1                        # a live sidecar on port 8080

セキュリティテストは必須であり、省略できません。クエリパス、書き込みパス、またはサンドボックスを変更する場合は、境界が引き続き守られることを証明するテストが必要です。さらに、サンドボックスはネイティブ SQLite ビルドに依存しているため、テストスイートは Linux コンテナに対してももう一度実行されます。別のプラットフォームでの開発者による実行では、リリースされる動作を証明できません。

(トップに戻る)

ライセンス

Apache-2.0。詳細は LICENSE をご覧ください。

連絡先

Pavel Osadchuk — xakpc.dev · github.com/xakpc

プロジェクト：github.com/xakpc/sqlite-mcp-sidecar

謝辞

• Model Context Protocol と C# SDK
• SQLite。本プロジェクトが利用するオーソライザーとオンラインバックアップ API を提供しています
• TOON
• Best-README-Template

(トップに戻る)