Model Context Protocol | Sqrzl Emulator

Connect to Sqrzl

Endpoint: http://localhost:9001/mcp
Transport: Streamable HTTP
Capabilities: Tools and resources

The MCP endpoint shares the UI and admin listener. Its default port is 9001 (SQRZL_UI_PORT); the provider storage endpoint on 9000 is separate. If you map a different host port, use that port in the MCP URL. Connect with an MCP client that supports Streamable HTTP; Sqrzl does not require a separate MCP process or a custom protocol.

Tools

Use the MCP client's tool discovery to see the schemas available from the running Sqrzl version. The tool set covers:

Buckets, lifecycle rules, policies, ACLs, and versioning, including bucket_list and bucket_create.
Object listing, content, metadata, tags, ACLs, versions, copy, delete, and multipart uploads. Binary content uses base64 fields, such as object_content_get and object_content_put.
Captured email and simulated text messages, including mail_send_simulate, text_send_simulate, inbound-message simulation, and delivery transitions.
Usage diagnostics through usage_query.

Tool calls use the same emulator services and stores as the admin UI and admin HTTP API, so changes and captured messages are visible there too. Email tools capture messages and text tools simulate delivery; neither sends to real recipients. Read tools use sqrzl:read; changes use sqrzl:write when OAuth is enabled.

Resources and metrics

Resource or endpoint	Purpose
`sqrzl://health`	Read the emulator health status as JSON.
`sqrzl://usage`	Read process-local usage rows for provider, bucket, client, operation, byte, and list activity.
`/metrics`	Export Prometheus text for request counts, bytes, request-size histograms, and list activity.

The usage resource and usage_query accept min_requests and min_bytes thresholds. The Prometheus endpoint accepts ?min_requests=N. Counters are held in memory and reset when Sqrzl restarts. When admin session auth is enabled, /metrics uses that admin session.

Authentication

MCP is open when provider authentication is off and SQRZL_MCP_AUTH_ENABLED is false. The checked-in Compose setup sets admin and sqrzl-secret, which protect MCP too; those credentials are not OAuth bearer tokens, and Compose does not configure OAuth by default. Add the OAuth settings below before using protected MCP, or remove both generic access-key variables for a local open session. Removing them also opens provider and admin APIs, so keep that listener bound to loopback.

Sqrzl does not issue OAuth tokens. It validates bearer tokens against the configured JWKS and checks token expiration, issuer, audience, and the scope needed for each read or write. The authorization server must issue tokens for the exact resource URL.

Scope	Access
`sqrzl:read`	Read tools and MCP resources.
`sqrzl:write`	Tools that create, update, simulate, or delete data.

When OAuth protection is configured, resource metadata is available at /.well-known/oauth-protected-resource/mcp. MCP clients send their token in the Authorization: Bearer header; admin UI/API cookie sessions remain separate.

OAuth configuration

Set all five resource-server values. The URLs below are examples; replace them with your authorization server's real endpoints and claims.

SQRZL_MCP_AUTH_ENABLED=true
SQRZL_MCP_RESOURCE_URL=https://sqrzl.example/mcp
SQRZL_MCP_AUTHORIZATION_SERVER=https://auth.example
SQRZL_MCP_ISSUER=https://auth.example/
SQRZL_MCP_AUDIENCE=https://sqrzl.example/mcp
SQRZL_MCP_JWKS_URL=https://auth.example/.well-known/jwks.json

SQRZL_MCP_RESOURCE_URL must be an absolute URL whose path is exactly /mcp. The resource and authorization-server URLs can use HTTP for local development; the JWKS URL must use HTTPS. The configured issuer and audience must exactly match the access token claims. See Configuration for other runtime settings.

Browser origins and host names