tasks

MCP Tasks for Go

Go support for the official io.modelcontextprotocol/tasks extension, 2026-07-28. This module targets the dated specification, not the draft or the incompatible 2025-11-25 Tasks API. Core MCP schemas remain in mcp-protocol; transports remain in viant/mcp. This module supplies extension types, policy/state interfaces, a reference durable store, an opt-in RPC decorator, and polling/streaming clients.

Quick start

Requires Go 1.25.5 or later.

go get github.com/viant/mcp-tasks

An existing runtime implements the small tasks.Backend interface. It creates an owned handle only after its native execution is durably admitted, projects that execution on Get, and delegates Update / Cancel to its ordinary control APIs. The optional reference implementation is useful for a small service or for testing a new adapter:

storage, err := store.Open("./task-state", 1000)
if err != nil { return err }
backend, err := reference.New(storage, reference.Options{})
if err != nil { return err }

caps := schema.ClientCapabilities{}
tasks.Advertise(&caps)
owner := tasks.Owner{Tenant: "my-service", Subject: authenticatedSubject}
handle, err := backend.Create(ctx, owner, caps, tasks.CreateOptions{
    Method: tasks.MethodCallTool,
})
// Return handle only after err == nil. Dispatch work through your existing
// executor; persist its original MCP result with backend.Complete(...).

Imports for this example are github.com/viant/mcp-tasks (alias tasks), github.com/viant/mcp-tasks/reference, github.com/viant/mcp-tasks/store, and github.com/viant/mcp-protocol/schema. A complete runnable example is in example_test.go.

An opt-in client handles either an ordinary result or a task handle:

caller, err := rpc.NewHTTPCaller(endpoint, authenticatedHTTPClient)
if err != nil { return err }
requester, err := client.New(caller, client.Options{
    Tasks: true,
    Info: schema.Implementation{Name: "my-client", Version: "1.0"},
})
if err != nil { return err }
outcome, err := requester.CallTool(ctx, &schema.CallToolRequestParams{
    Name: "generate_report",
})
if err != nil { return err }
if outcome.Task != nil {
    // Persist taskId and the input cursor to recover observation after restart.
    result, err := requester.Wait(ctx, outcome.Task.TaskID, client.WaitOptions{
        Initial: &outcome.Task.Task,
    })
    _ = result
    return err
}
// outcome.Result contains the unchanged regular or MRTR result.

Wait returns an InputRequiredError unless an explicit Input callback is provided. That callback must use the same sampling, elicitation, consent and approval policy as normal MCP requests. SaveCursor records input attempt state before side effects; a lost acknowledgement is not permission to retry it. Cancel explicitly acknowledges cancellation intent. Cancelling the observation context only stops polling and leaves native work running.

Design

A task is a durable view of an existing execution, not an execution scheduler. Store adapters may map the task directly onto an application's canonical run store. reference.Service maintains the reference task state; it does not start workers, retry operations, replay original tool calls, or cancel work on disconnect. The supplied file store is a small reference backend, not a replacement for Agently's existing durable execution engine.

The server decides whether to create a task for each tool request. The client must declare the extension in that request's _meta capabilities; declarations on another request or an older initialization do not authorize this response. Calls that do not use task augmentation keep their existing result and behavior. CreateTaskResult carries a flat Task seed, which can already have any status. Status-specific result/error/input payloads are fetched as DetailedTask through tasks/get or full-state notifications; seed decoding does not require them. The creator commits the owned record and verifies that it can be read before exposing its handle. Hosts that create work through the reference backend must schedule it only after this durable barrier; adapters may instead capture an already-admitted canonical native run.

Task IDs use 192 bits of random entropy, but are not treated as authorization. The caller supplies an authenticated tenant/subject identity from trusted request context. Every get, update and cancellation checks it; callers cannot select owners through wire parameters. Foreign and missing IDs have the same outcome. Input requests use lifetime-unique keys, durable response acceptance, and the same host consent/elicitation/sampling policy as their non-task equivalents. Cancellation records intent; its acknowledgement does not prove work stopped.

Packages and contract

• Root tasks: wire types, negotiation and backend/storage contracts.
• reference: optional lifecycle/state implementation, with no scheduler.
• store: file-backed durable reference implementation with process-safe locks, atomic replacement, file/directory sync, optimistic revisions and explicit expiry cleanup. It starts no executions.
• rpc: transport.Handler decorator, per-request authentication/negotiation, raw result dispatch, and a bounded HTTP JSON-RPC caller with task routing headers.
• client: task-aware tool results, polling, explicit update/cancel and optional input handling/checkpoints. Transport errors never retry a mutation or the original tool call; unknown input outcomes require reconciliation.

Store.Create and Store.CompareAndSwap must be atomic and durable before success. A failed/uncertain commit must not be repeated automatically. CAS conflicts may reread state and retry only the pure state mutation, never a worker or input-handler side effect. Host integrations own execution policy, quotas, job dispatch, approval, durable input delivery and recovery of uncertain work.

Integration boundary

The RPC decorator can wrap an existing JSON-RPC handler. Its owner resolver must perform the same authentication and authorization as the host; interception must not bypass a sibling handler's private authorization pipeline. Non-task methods delegate unchanged. A tool decision callback is read-only planning and policy, not worker dispatch. Discovery advertises Tasks only for a configured service. Optional subscription streams are not silently acknowledged.

Minimal native viant/mcp hooks needed for seamless high-level integration:

1. Extension dispatch after normal protocol/request-context/auth preparation, before its closed method switch, with raw JSON result support.
2. Preserve the tools/call result discriminator before decoding the fixed CallToolResult shape; opt-in callers can expose a handle or poll to completion.
3. Route Tasks requests by taskId in the Streamable HTTP Mcp-Name header and attach July per-request metadata. A raw transport supplied to this module can already carry extension requests without changing core schemas.
4. Tool-schema x-mcp-header discovery, validation and argument mirroring belong to the host/high-level MCP client. This raw Tasks client does not fetch/cache all tool schemas or claim that complete core client surface. A custom caller can provide those headers without replaying a call.
5. The supplied decorator already streams owned taskIds through its actual configured notifier. A native viant/mcp integration may compose this with its existing subscription hub. Mixed Tasks/base filters are rejected by the standalone decorator instead of silently dropping them.

For Agently, adapt these hooks to existing runs, deferred inputs, approvals, resume/cancel APIs and AG-UI projections; do not create another native task engine. Keep native causal links in the adapter's private record, not caller-supplied IDs. Existing async tool pairs (run/status/cancel), operation selectors, wait/detach and skill fork remain the native APIs and execution modes. MCP Tasks adapts them for interoperable clients; it does not deprecate or replace them.

Existing native fork/detach tests alone do not prove standard Tasks interoperability. The consuming adapter needs tests for each row over a real MCP connection, including lost responses, restart, foreign-owner polling, partial inputs and cancellation races. The Agently Core source adapter lives in sdk/mcp_tasks.go, with an opt-in transport wrapper in protocol/mcp/expose/tasks.go. It projects existing owned AG-UI/native executions and persists aliases/control receipts in the existing native store. Enabling it requires the host's trusted capture, exported-tool policy and owner resolver; importing this module does not automatically enable an endpoint or authorize arbitrary tools. No runtime/UI deployment is performed by this module.

Task subscription streams

Configure the actual notification transport before accepting taskIds:

handler := &rpc.Handler{
    Next: ordinaryMCPHandler,
    Service: nativeBackend,
    Owner: resolveAuthenticatedOwner,
    Notifier: requestScopedNotifier,
    Subscriptions: &rpc.SubscriptionOptions{
        ReconcileInterval: time.Second,
        MaxDuration: 5 * time.Minute,
    },
}

rpc.HTTPHandler supplies a request-scoped SSE notifier from a Build factory. Host middleware must prepare authentication/context before its owner resolver. The adapter rejects present Origins unless AllowOrigin explicitly admits them. It validates July routing headers before admission, decodes the standard Base64 sentinel for Mcp-Name, and returns HTTP 400/404 with correlated protocol errors. Callers preserve those error bodies; they do not interpret them as permission to retry a mutation or fall back to an unauthenticated transport. protocolVersion and clientCapabilities are required per request; clientInfo is optional. Authentication never derives from self-reported client metadata. Other transports can provide their existing transport.Notifier; stdio notifications/cancelled ends only the matching owned subscription. The HTTP client generates positive integer stream IDs; servers also accept valid MCP string/integer IDs. These IDs are present in every acknowledgement, notification and graceful result under _meta["io.modelcontextprotocol/subscriptionId"].

A backend may implement tasks.ChangeSource for bounded wakeup hints from its existing native event bus. The stream attaches hints before reading state, then re-reads Backend.Get after hints and periodically. Hints never carry MCP payloads. Dropped/overflowed events and process-local bus loss are recovered by canonical rereads; reconnect creates a fresh subscription and initial full-state snapshot. There is no execution replay or unbounded durable event backfill.

The typed client supports bounded HTTP observation and reconnect:

err := requester.Subscribe(ctx, []string{taskID}, client.SubscriptionOptions{
    MaxReconnects: 3,
    OnTask: func(state tasks.DetailedTask) error {
        renderOwnedTaskState(state)
        return nil
    },
})

Subscribe verifies acknowledgement order, agreed IDs, subscription correlation, state shape (including required ttlMs) and declared input capabilities. It only observes: input responses and task cancellation still require their explicit APIs and ordinary policy. Unexpected disconnects refresh canonical state and reconnect within the supplied budget; protocol errors and callback failures are not retried. Cancelling ctx closes the observer and leaves the task running.

Frames, selected IDs, per-handler active subscriptions, stream duration and reconnect count are bounded. Hosts own aggregate connection quotas when their factory creates a handler per request. Frame bytes are bounded independently of stream lifetime. Slow HTTP writes have a deadline; request cancellation cleans up event subscriptions. Mixed task/base filters, unrequested notification methods, unknown/foreign task IDs, missing Tasks capability, and input notifications without the corresponding client capabilities are rejected. No task list or cross-owner stream exists.

The dated core subscription contract and dated Tasks extension define these wire rules. Draft behavior is not enabled.

Testing and status

go test ./...
go test -race ./...
go vet ./...

Tests cover flat wire decoding, required/null fields, per-request capability negotiation, missing capability error -32021, owner/tenant isolation, atomic cross-instance storage, durable reopen, partial/deduplicated input, unique keys, TTL, tool versus protocol errors, cooperative cancellation and competing terminal transitions. Integration tests use the real viant/mcp handler and ordinary high-level client, a task-aware raw client, and HTTP routing headers. Streaming tests cover real HTTP acknowledgement and full states, bounded reconnect with canonical refresh, stdio observer cancellation, owner/tenant rejection, input-capability checks after acknowledgement, malformed or unrequested frames, and frame budgets independent of stream lifetime. No live service, application account, credentials or UI is required.

The dated Tasks request/poll/update/cancel contract is implemented and tested. Task subscription streaming is implemented behind explicit transport enablement. The decorator rejects subscription requests unless both Subscriptions options and a real Notifier are configured. It emits acknowledgement first, full state only, and a correlated graceful completion; it never forwards task progress or logging events. Mixed task/base subscriptions require host composition and are rejected explicitly by this standalone adapter. The older 2025-11-25 API is deliberately separate. Production store retention, quotas, process shutdown, request authentication, native scheduling and recovery are host responsibilities. Tests do not certify an application's deployment.

License

Apache License 2.0. See LICENSE and NOTICE.