Fast Startup: Async Server Loading

Async loading makes the HTTP listener available before configured static MCP servers finish connecting. It does not make every MCP client safe to use an incomplete capability catalog.

Default and Compatibility

Synchronous startup is the default. It waits to publish a complete initial catalog and is the safe choice unless client behavior is known.

Client behavior	Recommended startup	Reason
Reads the catalog once and never refreshes	Synchronous (default)	It requires the complete initial catalog.
Handles capability-list change notifications and retries discovery	Async is suitable	It can reconcile after a new snapshot is published.
Is gated from using the catalog until loading completes	Async is suitable	The deployment gate protects its first catalog read.
Unknown or mixed compatibility	Synchronous (default)	Notification support is unverified.

Enable async loading only when early HTTP availability is worth this contract:

npx -y @1mcp/agent --config mcp.json --enable-async-loading

Catalog Publication

In async mode, the early catalog can be empty. 1MCP connects static backends in the background, builds the next capability snapshot, then publishes that snapshot atomically. It does not progressively expose one newly connected server at a time.

Compatible clients must process capability-list change notifications and retry discovery. A client that ignores those notifications can retain the empty or prior catalog until it reconnects.

Client-Facing Status

Use the authenticated /api/v1/inspect endpoint or its CLI equivalent for client-facing status. It lists configured static servers before the first atomic capability snapshot. Known unavailable static servers return a normal inspect result with no tools; unknown names remain not found.

Async loading options

CLI option	Default	Purpose
--async-batch-notifications	Enabled	Coalesces capability-change events into fewer listChanged notifications. Use --no-async-batch-notifications to send each published change immediately.
--async-batch-delay <milliseconds>	1000	Coalescing window used when notification batching is enabled.
--async-notify-on-snapshot	Enabled	Sends notifications when a completed loading cycle publishes a changed capability snapshot. Global --enable-client-notifications must also remain enabled.
--async-notify-on-ready	—	Deprecated compatibility alias for --async-notify-on-snapshot. If both are supplied, --async-notify-on-snapshot wins.
--async-min-servers, --async-timeout	—	Deprecated compatibility no-ops. Their ONE_MCP_* environment variables and asyncLoading.minServers / asyncLoading.timeout TOML keys warn when explicitly supplied and will be removed next major.

A longer batch delay reduces notification bursts at the cost of delaying notifications after a changed snapshot is published. It does not delay listener availability or create a readiness gate.

npx -y @1mcp/agent --config mcp.json --enable-async-loading \
  --async-notify-on-snapshot \
  --async-batch-delay 250

Configuration

You can customize the async loading behavior, such as timeouts and retry logic, in the loading section of your JSON configuration file.

For a complete list of options, see the Configuration Deep Dive.

1mcp inspect
1mcp inspect filesystem
1mcp wait
1mcp wait filesystem --timeout 60000

wait only tracks enabled configured static servers. It excludes templates and disabled servers, never cancels background loading, and stops immediately for failed, cancelled, or awaiting_oauth states. run checks this client-facing status before falling back to MCP, so it returns a recovery command while a backend is loading instead of attempting an unsafe early invocation.

State	Meaning	Action
pending / loading	Startup is still in progress	1mcp wait <server>
failed / cancelled	No usable backend is available	Check configuration or restart the backend
awaiting_oauth	Provider authorization is required	Complete the OAuth flow shown by inspect
connected	The backend connection is established; invocation also requires available: true	Inspect or run tools after availability is confirmed

Health Endpoints

/health/ready and /health/mcp answer different questions:

• /health/ready reports whether runtime configuration is ready to accept HTTP traffic. It is not a claim that every MCP backend has completed startup.
• /health/mcp is the operational backend-progress view, including loading and retry detail.

curl http://localhost:3050/health/ready
curl http://localhost:3050/health/mcp

Use the inspect API or CLI for an authenticated caller deciding whether to invoke a tool. Use health endpoints for monitoring.

Configuration Notes

Async loading remains opt-in. This page describes the runtime contract rather than deprecated-option cleanup; use current command help and the configuration reference for supported options.

Related work: #393 tracks obsolete async option cleanup, and #405 defines the CLI status and wait workflow.