Skip to content

DX-3022: docs: MCP Tasks and MCP Events (@upstash/mcp-toolkit) under AgentKit and the QStash TS SDK - #901

Merged
CahidArda merged 16 commits into
mainfrom
dx-3022-mcp-tasks-docs
Oct 8, 2026
Merged

DX-3022: docs: MCP Tasks and MCP Events (@upstash/mcp-toolkit) under AgentKit and the QStash TS SDK#901
CahidArda merged 16 commits into
mainfrom
dx-3022-mcp-tasks-docs

Conversation

@CahidArda

@CahidArda CahidArda commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Docs for @upstash/mcp-toolkit (upstash/agentkit#38): /tasks (durable long-running MCP tools) and /events (MCP Events with webhook delivery), with the Upstash backends in /upstash.

  • redis/sdks/agentkit/mcp-tasks (new): long-running tools. A tool answers with a task id at once, the work runs on QStash or Upstash Workflow, the record lives in Redis, and the model polls task_status. Covers a four-file quickstart (principal, tasks.define / tasks.register, the MCP route, the execute route), what the model sees, cancellation, users and principal, WorkflowDispatcher and its handler rules, retries and failures, who can see what, what is stored in Redis, options, custom backends, and why plain tools instead of the protocol's Tasks extension.
  • redis/sdks/agentkit/mcp-events (new): MCP Events for your server. A quickstart (principal, the event layer, the server, the MCP route, the delivery route) with typed events.define(...) and emit, the wire format, matching and the required authorize (at subscribe and before every delivery), users and subscriptions, security checks (callback verification, URL rules, encrypted secrets), host responses, what is stored in Redis, options, and custom backends and receivers.
  • Both pages are listed in both AgentKit groups (SDKs and Integrations). The QStash TypeScript SDK sidebar gets a stub for each (qstash/sdks/ts/mcp-tasks, qstash/sdks/ts/mcp-events) that redirects to the page, the same pattern as redis/search/command-reference.
  • llms.txt and llms-full.txt are regenerated.

Updated to the API after upstash/agentkit#60: tasks.define + tasks.register, a single @upstash/mcp-toolkit/upstash backend entry point, required principal and authorize, no idempotencyKey and no onSettle / task.finished bridge.

Draft until upstash/agentkit#38 merges and the package is published. The pages link to the demo on agentkit main. Blog post: upstash/upstash-web#682.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bv5rWc6Uy6uqCwwDpMN1HJ

@CahidArda @claude
DX-3022: docs: add MCP Tasks under AgentKit and the QStash TS SDK
62eeb68 
One page, redis/sdks/agentkit/mcp-tasks, for @upstash/mcp-tasks: durable
long-running MCP tools on Redis and QStash/Workflow. It sits next to the other
AgentKit packages in both AgentKit groups.

The QStash TS SDK sidebar gets a stub at qstash/sdks/ts/mcp-tasks that
redirects to it (same pattern as redis/search/command-reference). llms.txt
and llms-full.txt regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nt2iNfw9zcDS5T2bBgquUd
@mintlify

mintlify Bot commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
upstash 🟢 Ready View Preview Oct 8, 2026, 9:53 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@linear-code

linear-code Bot commented Oct 7, 2026

Copy link
Copy Markdown

DX-3022

@context7

context7 Bot commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Docs7 for upstash.com

Result Status Action
Deployment ✅ Ready Open preview
Content review ⏳ In progress —

Commit 60d9821 · Updated 2026-10-08 21:56 UTC · View build details

@CahidArda CahidArda mentioned this pull request Oct 7, 2026
Merged
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 7, 2026 12:24 Destroyed
@context7 context7 Bot mentioned this pull request Oct 7, 2026
Closed
@CahidArda @claude
DX-3022: docs: MCP Events page, @upstash/mcp-toolkit imports
ad0bef5 
The package is now @upstash/mcp-toolkit. The MCP Tasks page uses the
/tasks imports and gains onSettle plus a "push instead of poll" section.
New page redis/sdks/agentkit/mcp-events for /events, in both AgentKit
groups, with a QStash TS SDK stub that redirects to it. llms regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nt2iNfw9zcDS5T2bBgquUd
@CahidArda CahidArda changed the title DX-3022: docs: MCP Tasks under AgentKit and the QStash TS SDK DX-3022: docs: MCP Tasks and MCP Events (@upstash/mcp-toolkit) under AgentKit and the QStash TS SDK Oct 7, 2026
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 7, 2026 13:39 Destroyed
context7 Bot added a commit that referenced this pull request Oct 7, 2026
@context7
docs: 1 review fix for #901 (grammar and spelling)
a0dffc1
@CahidArda @claude
DX-3022: docs: single /events import, users and subscriptions section…
76df372 
…, Deploy Watch example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWZjexwCU7VKGGrJ3oxrKK
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 09:37 Destroyed
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 10:40 Destroyed
@CahidArda @claude
DX-3022: docs: address the review
6476cb4 
- tasks.define/register, required principal and signing keys in every snippet
- events: secretKey shown, every emit names owner or owners, a {} subscription
  only hears about its own user, one generic -32015 for failed verification,
  stricter callback checks, 489 non-retryable for bad deliveries, redirects dropped
- tasks: QStash work is bound by the function limit; Workflow needs the type
  argument, steps and a longer ttlMs; task_status prepends a status line; data at
  rest note; a coherent task.finished example, untested with ChatGPT

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWZjexwCU7VKGGrJ3oxrKK
@CahidArda
CahidArda force-pushed the dx-3022-mcp-tasks-docs branch from 8a4912b to 6476cb4 Compare October 8, 2026 11:44
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 11:46 Destroyed
@CahidArda @claude
DX-3022: docs: explain AuthInfo, principal receives { auth, request }
952996f 
- the Users section explains what auth (AuthInfo) is and that the MCP route
  populates it via handler.fetch(request, { authInfo }) after verifying the token
- principal receives { auth, request } and may be async; request is for
  cookie/session apps and is unverified

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWZjexwCU7VKGGrJ3oxrKK
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 12:02 Destroyed
@CahidArda @claude
DX-3022: docs: authorize at subscribe and delivery, optional to, ty…
ad080d7 
…ped args

- emit needs no recipients; authorize is required and re-checked before each delivery
- principal may return { id, context } for the delivery-time check; the token is
  never stored
- personal events require `to`; args is required when the payload lacks an input field

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWZjexwCU7VKGGrJ3oxrKK
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 12:21 Destroyed
@CahidArda @claude
DX-3022: docs: /upstash imports, principal throws to refuse, drop ide…
87222dd 
…mpotencyKey

- Upstash backends import from @upstash/mcp-toolkit/upstash; one npm install
- principal returns an id and throws when it can't; no `as string | undefined`
- idempotencyKey section removed
- Workflow: no type argument (inferred), a complete example task

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A5x4btgiRE3FKdpUW527Wu
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 13:08 Destroyed
@CahidArda
DX-3022: docs: match the simplified mcp-toolkit API
e2845e7 
- events: emit(payload, { eventId? }) only; every input field is a payload
  field; authorize gets the event's values at delivery; drop to/personal/
  match/explicit args, principal context, task.finished, timeoutMs/defaults
  and QStashDelivery retries/headers options.
- tasks: drop onSettle/taskFinishedEvent, toolNames, queuedMessage, per-tool
  ttlMs/pollIntervalMs and ttlMs: null.
- principal defined once in lib/auth.ts with the SDK's AuthInfo; the MCP
  route types authInfo as AuthInfo.
- New custom backend interfaces, Workflow signatures bound to the URL,
  MCP_EVENTS_SECRET_KEY >= 32 bytes, every IP literal refused.
- Minimal snippets, details in Accordions, as in the package README.

Claude-Session: https://claude.ai/code/session_012geGTRLRnPqYtaASmBdhE1
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 14:35 Destroyed
@CahidArda CahidArda mentioned this pull request Oct 8, 2026
Merged
CahidArda and others added 2 commits October 8, 2026 15:13
@CahidArda @claude
DX-3022: docs: MCP Tasks default TTL is 1 day
f99d1b4 
Follows upstash/agentkit#38, where the default task TTL went from 5 minutes to 1 day.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bv5rWc6Uy6uqCwwDpMN1HJ
@github-actions
chore(llms): regenerate llms.txt and llms-full.txt
0a9aa8c
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 15:18 Destroyed
@CahidArda @claude
DX-3022: docs: task authorize + task.principal, subscription limit, i…
0ef135c 
…nput-schema routing

- MCP Tasks: 'Check what the arguments point at' section (authorize on tasks.define, task.principal in the handler); migrate_workspace example uses both; options and custom-backend notes
- MCP Events: maxSubscriptions (8 per subscriber) and the subscription_limit reason; routing values parsed with the input schema; eventId dedup now via webhook-id; by:<subscriber> key; SubscriptionStore interface

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gtucop3k8CNVLjgvoDTC8n
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 21:17 Destroyed
@CahidArda @claude
DX-3022: docs: show where AuthInfo is built (mcp-handler withMcpAuth)
8233ad5 
lib/auth.ts now holds verifyToken (builds AuthInfo, wired with withMcpAuth) next to principal; the MCP route uses mcp-handler's createMcpHandler + withMcpAuth, as upstash-mcp-server does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gtucop3k8CNVLjgvoDTC8n
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 21:29 Destroyed
@context7 context7 Bot mentioned this pull request Oct 8, 2026
Closed
@context7
context7 Bot temporarily deployed to Docs7 Preview: dx-3022-mcp-tasks-docs October 8, 2026 21:56 Destroyed
@CahidArda
CahidArda marked this pull request as ready for review October 8, 2026 22:03
@CahidArda
CahidArda merged commit 84a612a into main Oct 8, 2026
3 of 4 checks passed
@CahidArda
CahidArda deleted the dx-3022-mcp-tasks-docs branch October 8, 2026 22:03

This branch was successfully deployed

1 active deployment
Docs7 Preview: dx-3022-mcp-tasks-docs — 60d9821b Deployed Oct 8, 2026 by context7[bot]
staging — 60d9821b Deployed Oct 8, 2026 by mintlify[bot]
View deployment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@CahidArda