Skip to content

Core Concepts

What you'll learn here: the core model behind sessions, upload handles, artifact URIs, and passthrough tools.

Sessions

Every connection is scoped by Mcp-Session-Id. The adapter treats that session ID as the isolation boundary for uploads, artifacts, and quotas.

If a session expires (idle TTL or teardown), its staged uploads and artifacts are cleaned up by background cleanup.

Example request header:

POST /mcp/playwright HTTP/1.1
Mcp-Session-Id: a3f8c2d1-7b4e-4f9a-85cc-0e3d1f6a9b12
Content-Type: application/json

File inputs: upload:// handles

Why local paths fail remotely

A path like /Users/me/report.pdf exists on the client machine, not on the upstream MCP server machine. Remote upstream tools cannot read it directly.

The fix is to stage the file first, then pass an upload:// handle to the tool.

Upload workflow

If a server has at least one upload_consumer adapter and uploads.enabled: true, the adapter registers a helper tool named <server_id>_get_upload_url (for example playwright_get_upload_url).

The client flow is:

  1. Call <server_id>_get_upload_url(...).
  2. POST file(s) to the returned upload URL.
  3. Receive upload:// handle(s).
  4. Pass those handles in the configured tool argument.

Handle format:

upload://sessions/<session-id>/<upload-id>

Example:

upload://sessions/a3f8c2d1-7b4e-4f9a-85cc-0e3d1f6a9b12/7f3c81a0-2b4d-4e6f

File outputs: artifact:// URIs

What artifact capture does

For tools configured as artifact_producer, the adapter captures produced files into session-scoped artifact storage and registers them as MCP resources.

The adapter returns artifact metadata under meta.artifact (including artifact_uri). It does not depend on rewriting arbitrary text in the tool output.

Artifact URI format:

artifact://sessions/<session-id>/<artifact-id>/<filename>

Example:

artifact://sessions/a3f8c2d1-7b4e-4f9a-85cc-0e3d1f6a9b12/c91d3e7f-5a2b-4c8d/screenshot.png

Clients can call resources/read on that URI to fetch bytes. If core.allow_artifacts_download is enabled, artifact metadata may also include download_url.

Passthrough tools

Any tool not listed in upload_consumer or artifact_producer config is passthrough. The adapter forwards arguments and returns results unchanged.

Next steps