Documentation
¶
Overview ¶
Package mcptasks adds the Tasks extension (io.modelcontextprotocol/tasks, spec 2026-07-28) to a server built on the official go-sdk, which does not support it yet.
A tool registered as task-capable answers tools/call with a task handle (resultType "task") when the client declares the extension on that request, runs in the background and is polled with tasks/get. Clients without the extension get the normal synchronous result. The tool can ask the client for input while it runs (status input_required) with RequestInput.
caps := &mcp.ServerCapabilities{}
mcptasks.Declare(caps)
s := mcp.NewServer(impl, &mcp.ServerOptions{Capabilities: caps})
mcp.AddTool(s, tool, handler)
mcptasks.Enable(s, mcptasks.NewStore(), "generate_image")
s.Connect(ctx, mcptasks.GuardListen(&mcp.StdioTransport{}), nil)
GuardListen (or GuardListenHandler for Streamable HTTP) refuses requests for task notifications from clients without the extension, which the go-sdk cannot do itself. Task notifications are not sent; clients poll.
Tasks are bound to the identity that created them (Store.Owner, by default the bearer token's user id or a digest of the token): another identity gets -32602 as for an unknown task.
Index ¶
- Constants
- func Declare(caps *mcp.ServerCapabilities)
- func DefaultOwner(extra *mcp.RequestExtra) string
- func Enable(s *mcp.Server, store *Store, toolNames ...string) error
- func GuardListen(t mcp.Transport) mcp.Transport
- func GuardListenHandler(h http.Handler) http.Handler
- func IsTask(ctx context.Context) bool
- func RequestInput(ctx context.Context, requests mcp.InputRequestMap) (mcp.InputResponseMap, error)
- type AckResult
- type OwnerFunc
- type Store
- type TaskParams
- type TaskResult
- type UpdateParams
Constants ¶
const ( Working = "working" InputRequired = "input_required" Completed = "completed" Failed = "failed" Cancelled = "cancelled" )
Task statuses.
const Extension = "io.modelcontextprotocol/tasks"
Extension is the identifier of the Tasks extension.
Variables ¶
This section is empty.
Functions ¶
func Declare ¶
func Declare(caps *mcp.ServerCapabilities)
Declare adds the extension to the server capabilities (for server/discover).
func DefaultOwner ¶ added in v1.8.0
func DefaultOwner(extra *mcp.RequestExtra) string
DefaultOwner is the user id of the verified bearer token or, if the verifier sets none, a digest of the Authorization header — then a task is bound to the token, and a refreshed token no longer reaches it. Set Store.Owner when the verifier knows a stable identity it does not put into TokenInfo.UserID.
func Enable ¶
Enable registers the middleware and the tasks/* methods; toolNames are the tools that may run as a task.
func GuardListen ¶ added in v1.8.0
GuardListen wraps a server transport (e.g. stdio) so that such requests are refused with -32021 before they reach the SDK.
func GuardListenHandler ¶ added in v1.8.0
GuardListenHandler wraps a Streamable HTTP handler likewise: such a request gets the -32021 error as a JSON response.
func RequestInput ¶
func RequestInput(ctx context.Context, requests mcp.InputRequestMap) (mcp.InputResponseMap, error)
RequestInput asks the client for input while a task runs: the task turns input_required with requests until the client answers via tasks/update. Outside a task it returns an error, so the tool can fall back (e.g. to a multi round-trip InputRequiredResult). Keys must be unique over the task's lifetime.
Types ¶
type AckResult ¶
type AckResult struct {
mcp.ResultBase
ResultType string `json:"resultType"`
}
AckResult is the empty acknowledgement of tasks/update and tasks/cancel.
type OwnerFunc ¶ added in v1.8.0
type OwnerFunc func(extra *mcp.RequestExtra) string
OwnerFunc returns the identity a request acts for; a task is bound to the identity that created it, and tasks/get, tasks/update and tasks/cancel of another identity find no task (-32602), as for an unknown id. "" means no identity: such tasks are protected by their unguessable id only.
type Store ¶
type Store struct {
// TTL is reported as ttlMs; finished tasks are dropped after it.
TTL time.Duration
// PollInterval is suggested to clients as pollIntervalMs.
PollInterval time.Duration
// Owner binds tasks to identities (default DefaultOwner).
Owner OwnerFunc
// contains filtered or unexported fields
}
Store keeps the tasks of one server. The zero value is ready to use.
type TaskParams ¶
type TaskParams struct {
mcp.ParamsBase
TaskID string `json:"taskId"`
}
TaskParams are the params of tasks/get and tasks/cancel.
type TaskResult ¶
type TaskResult struct {
mcp.ResultBase
ResultType string `json:"resultType"`
TaskID string `json:"taskId"`
Status string `json:"status"`
StatusMessage string `json:"statusMessage,omitempty"`
CreatedAt string `json:"createdAt"`
LastUpdatedAt string `json:"lastUpdatedAt"`
TTLMs *int64 `json:"ttlMs"`
PollIntervalMs int64 `json:"pollIntervalMs,omitempty"`
Result json.RawMessage `json:"result,omitempty"`
Error *jsonrpc.Error `json:"error,omitempty"`
InputRequests mcp.InputRequestMap `json:"inputRequests,omitempty"`
}
TaskResult is a Task as returned by tools/call (resultType "task") and tasks/get (resultType "complete", with the status-specific fields).
type UpdateParams ¶
type UpdateParams struct {
mcp.ParamsBase
TaskID string `json:"taskId"`
InputResponses json.RawMessage `json:"inputResponses"`
}
UpdateParams are the params of tasks/update.
Source Files