The Upstash MCP server lets your agent manage and debug your Upstash resources directly, across Redis, QStash, Workflow, Vector, Search, Upstash Box, and Blob.
Run it two ways:
- Remote (hosted) — nothing to install. Connect over HTTP to
https://mcp.upstash.com/mcpwith OAuth or a developer API key. Covers Redis, QStash, Workflow, Vector, Search, Box, and Blob, plus an interactive console in ChatGPT. - Local (stdio) — run
@upstash/mcp-serverwithnpx, authenticated with your email and API key. Covers Redis, QStash, Workflow, and Upstash Box.
Only running commands against a single Redis database? Use the dedicated Redis MCP with only that database’s REST/TCP credentials.
Remote server (recommended)#
Connect any MCP client over streamable HTTP to:
Tokens never reach the agent: data-plane tools resolve each resource’s REST credentials server-side and call the endpoint directly.
Connect#
Snippets for popular clients. For every client — and the plugin-based setup — see Install by agent.
Then run /mcp → Authenticate.
Edit ~/.cursor/mcp.json (or .cursor/mcp.json in a project):
Edit ~/.config/opencode/opencode.json (or a project opencode.json):
Add to ~/.codex/config.toml (or .codex/config.toml):
The Upstash plugin for Claude Code, Claude Desktop, and Codex bundles this remote MCP server (over OAuth), so installing the plugin sets up the skills and the MCP in one step — no separate command. See Install by agent.
Authentication#
Two ways in — the remote server verifies neither locally; the Upstash API is the authority.
OAuth (default)#
The first tool call opens a browser consent page where you pick the account scope (personal or a team) and whether the connection is read-only. The grant is per client and revocable from the console under Account → OAuth Clients. Nothing to configure — this is what the Connect snippets above use.
Developer API key (headless / CI)#
No browser. Pass an API key as an Authorization header, in the form email:API_KEY:
Create a key from the console — see Developer API → Create an API key.
Read-only API keys (and read-only OAuth grants) are supported — the server then disables every tool that would change state, and credential fields are omitted from tool results.
Feature groups#
Append ?features= to the URL to scope which product tools the agent sees — comma-separated values from redis, qstash_workflow, vector_search, box, blob, console; omitted means all six:
A group covers every product it names, because those products share their tools: qstash_workflow carries the QStash and Workflow tools, and vector_search carries the Vector and Search tools. Each product’s own name works as an alias for its group — qstash, workflow, vector and search are all accepted — so ?features=vector and ?features=vector_search return the same tools.
box and blob are the two halves of one workflow — an agent works in a sandbox, then gets what it produced out of it as a URL — so a client scoping down to that names both: ?features=box,blob.
console adds the console MCP App.
A name the server does not recognize is dropped, so ?features=redis,typo still returns the Redis tools. But if every name is dropped, the server starts with no tools at all — and a client then reports tools/list as an unknown method rather than showing an empty list. If a fresh connection looks like it has no tools, check the spelling here first.
Tools#
74 tools, grouped the way ?features= groups them. The access column is the tool’s own annotation, which clients use to decide what to confirm with you: read never changes anything, write only adds, destructive can delete or overwrite what is already there. On a read-only connection every write and destructive tool is refused.
The management tools that describe a resource (redis_get_database, redis_create_database, index_get, index_create, qstash_list_users) return its REST credentials only when called with include_credentials: true, so a routine lookup never carries a secret into the conversation. Listings never include credentials, and on a read-only connection they are omitted regardless.
The plan, Prod Pack and budget tools change what your account is billed. They don’t quote prices: each links the product’s pricing page in its machine-readable form (for example https://upstash.com/pricing/redis.md) and tells the agent to give you the price and get your confirmation before calling. Budgets are whole US dollars, 0 for no cap or 20 to 10,000. Read regions count too: on a fixed plan each one adds the plan’s per-region price. Moving a Redis database back to the free plan and the enterprise tiers aren’t available through the MCP server; use the console or contact sales.
Redis — 18 tools
| Tool | Access | What it does |
|---|---|---|
redis_list_databases | read | Every Redis database in the account scope |
redis_get_database | read | One database in detail; REST credentials with include_credentials |
redis_get_stats | read | Throughput, latency, data size, hits and misses over a period; refresh recomputes the figures first |
redis_get_insights | read | Latency, throughput and replication lag per region, error counters, and anomalies the backend found |
redis_get_traffic | read | Where clients connect from, which SDKs they use, and how requests are routed |
redis_list_backups | read | Backups taken of a database |
redis_create_database | write | Creates a database, optionally on a given plan; returns its credentials with include_credentials |
redis_create_backup | write | Takes a manual backup |
redis_rename_database | destructive | Renames a database, replacing its current name |
redis_set_eviction | destructive | Turns key eviction on or off |
redis_set_auto_upgrade | destructive | Turns automatic plan upgrade on or off |
redis_change_plan | destructive | Moves a database to pay-as-you-go or a fixed tier, optionally setting Prod Pack and auto-upgrade too |
redis_set_prod_pack | destructive | Turns the Prod Pack add-on on or off |
redis_set_budget | destructive | Sets the monthly spending cap of a pay-as-you-go database |
redis_update_read_regions | destructive | Replaces a global database’s read regions with the list you give it, at most once every 30 minutes |
redis_reset_credentials | destructive | Replaces the password and REST tokens; clients using the old ones stop working |
redis_delete_database | destructive | Deletes a database and everything in it |
redis_run_command | destructive | Runs Redis commands over the REST API, one or a pipeline |
redis_run_command is annotated destructive because it takes arbitrary commands. On a read-only connection it still works, but only for commands on an allowlist of read-only ones — anything else, including a command the server does not recognize, is refused.
QStash and Workflow — 15 tools
Every tool here takes a region (eu or us), which picks the QStash user. The three shared ones take a service (qstash or workflow) to say which side you mean.
| Tool | Access | What it does |
|---|---|---|
qstash_list_users | read | The QStash user per region with its plan, Prod Pack state and budget; REST tokens and signing keys with include_credentials |
qstash_get_stats | read | Messages, runs, cost and bandwidth per day; today’s counts by outcome over a period; parallelism and DLQ size. refresh recomputes the figures first |
qstash_list_schedules | read | Schedules in a region |
qstash_flow_control_get | read | Rate and parallelism for a flow-control key, or the account’s global parallelism |
logs_list | read | Delivery and run logs, paginated by cursor; pass workflowRunId to inspect one run |
dlq_list | read | The dead-letter queue, paginated by cursor |
qstash_publish_message | write | Publishes a message to a destination URL |
qstash_flow_control_manage | destructive | Pauses, resumes, pins, unpins or resets the rate on a key |
qstash_manage_schedule | destructive | Creates, reads, deletes, pauses or resumes a schedule |
workflow_manage_run | destructive | Live steps of a running run, or cancels it |
dlq_manage | destructive | Reads or deletes a DLQ entry; Workflow entries can also be restarted or resumed |
qstash_set_plan | destructive | Moves the region’s QStash user, shared by QStash and Workflow, to pay-as-you-go or a fixed tier |
qstash_set_prod_pack | destructive | Turns the Prod Pack add-on on or off |
qstash_set_budget | destructive | Sets the monthly spending cap of a pay-as-you-go QStash user |
qstash_reset_token | destructive | Replaces the region’s token and read-only token, shared by QStash and Workflow; signing keys stay the same |
Workflow run IDs start with wfr_. A cancel is asynchronous; check logs_list to confirm it.
Vector and Search — 20 tools
A Search database is a Vector index whose named indexes are namespaces, so most tools serve both and take a service (vector or search). Only querying and writing documents differ, which is why those four keep product names.
| Tool | Access | What it does |
|---|---|---|
index_list | read | Every Vector index or Search database in the account scope |
index_get | read | One of them in detail; REST tokens with include_credentials |
index_get_stats | read | Queries and updates per day, throughput, latency and cost |
index_info | read | Document counts, index size, per-namespace breakdown |
index_list_namespaces | read | Namespaces, which for Search are its named indexes |
index_fetch | read | Documents by ID or ID prefix |
index_range | read | Pages through the documents of a namespace |
index_create | write | Creates a Vector index or a Search database; tokens with include_credentials |
index_set_plan | destructive | Moves a paid Vector index or Search database between pay-as-you-go and fixed |
index_reset_credentials | destructive | Replaces the REST token and read-only token; clients using the old ones stop working |
index_update | destructive | Edits one document in place, including a metadata patch mode |
index_rename_namespace | destructive | Renames a namespace |
index_delete | destructive | Deletes an index or database and everything in it |
index_delete_documents | destructive | Deletes documents by ID, prefix or filter |
index_reset | destructive | Empties a namespace, or every namespace, keeping the index |
index_delete_namespace | destructive | Deletes a namespace and its contents |
vector_query | read | Vector similarity search, with server-side embedding optional |
search_query | read | Full-text and semantic search over one named index |
vector_upsert | destructive | Upserts vectors, or text for the server to embed; an existing ID is overwritten |
search_upsert | destructive | Upserts documents, creating the named index if needed; an existing ID is overwritten |
Box — 14 tools
Sandboxed cloud containers with a shell, a filesystem, git and an optional headless browser. Each tool takes an action, so the names and parameters match the local server’s Box tools.
| Tool | Access | Actions |
|---|---|---|
box_logs | read | Timestamped log entries from a box, filterable by source, level, text and time window |
box_metrics | read | current, history, tokens, steps, step_diff — CPU, memory and disk for one box, token spend by day, and the steps of an agent run with their diffs |
box_account | read | summary, billing, logs — each active box with its cost (status: deleted for the deleted ones), this month’s totals, and log lines across all boxes |
box_browser | write | goto, content, screenshot, tabs, tab_new, tab_close, live_view — needs a box created with browser: true |
box_git | destructive | clone, status, diff, commit, checkout, push, create_pr, create_issue — authenticated by the GitHub installation linked to the account |
box_manage | destructive | create, list, get, status, delete, pause, resume, fork, reset — delete takes one box_id or up to 50 box_ids; create also takes init_command, skills, network_policy, attach_headers, mcp_servers and a git identity |
box_exec | destructive | Runs a shell command (argv array, optional folder) and waits for it; an inline program is ['node', '-e', code] or ['python3', '-c', code] |
box_schedules | destructive | create, list, get, update, pause, resume, delete — cron schedules that run a command or an agent prompt in a box |
box_config | destructive | get, set_model, add_label, remove_label, add_skill, remove_skill, add_mcp_server, remove_mcp_server, set_network_policy, set_git_identity, get_init_command, set_init_command, delete_init_command — settings of a running box |
box_env | destructive | list, set, set_all, delete — account-level environment variables, merged into every box created afterwards |
box_preview | destructive | create, list, delete — public URLs for ports in a box |
box_runs | destructive | list, get, cancel — a box’s run history |
box_snapshots | destructive | create, list, list_all, delete, restore |
box_apikey | destructive | list, create, delete — Box API keys for the account scope; create returns the secret once |
box_git clone is what writes the GitHub credentials into the box, so a repository cloned with git in box_exec cannot push or create_pr. A clone lands at /workspace/home/<repo>; pass that as folder on later calls. A Box API key made with box_apikey outlives the OAuth grant that created it — revoke it from the console when it is no longer needed. box_env is not a secrets store; a value set there lands in the environment of every future box.
Blob — 4 tools
Object storage for getting files an agent produced somewhere else — a screenshot in a box, a build in CI — into a bucket, back out as a URL, and gone again once they are no longer needed. Bytes never pass through the MCP server: the tools handle paths, links and metadata only.
| Tool | Access | Actions |
|---|---|---|
blob_bucket | destructive | list, get, stats, create, delete, reset_token — get returns the bucket token with include_credentials; stats returns storage, bandwidth, operations and cost per day and month; create defaults to a public bucket, whose objects get a permanent URL; delete is refused while the bucket still holds objects; reset_token rotates the bucket token |
blob_upload_url | write | Mints presigned PUT URLs for paths in a bucket, valid for at most 10 minutes |
blob_download_url | read | Mints presigned GET URLs for objects, valid for at most 10 minutes |
blob_object | destructive | list, delete — list pages through objects, 1,000 at a time, under an optional prefix; delete removes exact paths (up to 1,000) |
Upload with the returned headers sent verbatim — they are part of the signature, and a changed or missing one is refused by storage. Deleting a path that is already gone counts as deleted, and the result lists anything storage kept under failed. To remove a bucket, empty it first: list a page, delete its paths, repeat until the list comes back empty. On a read-only connection blob_upload_url, blob_object delete and blob_bucket create/delete are refused, and get returns no token.
Console — 3 tools
| Tool | Access | What it does |
|---|---|---|
upstash_console | read | Opens the console, optionally on a product, resource and tab |
console_redis_keys | read | Used by the console page to list keys |
console_redis_value | read | Used by the console page to read a key |
Console (MCP App)#
In ChatGPT and other hosts that support MCP Apps, the server shows the Upstash console inside the conversation. It’s on by default. Open it from the app sidebar, or ask something like “show me my Redis databases”.
| Product | What you can do |
|---|---|
| Redis | Browse and edit keys, run commands, view stats and Insights (with Prod Pack), create and delete databases; on Settings, change the plan, Prod Pack, budget, read regions, eviction and auto-upgrade, and reset credentials |
| QStash | Publish messages, manage schedules, read logs and the DLQ, view stats; on Settings, change the region’s plan, Prod Pack and budget, and reset its token (shared with Workflow) |
| Workflow | Trigger runs, inspect and cancel them, retry from the DLQ, view stats |
| Vector and Search | Browse documents by namespace, view stats; see the plan on Settings, switch a Vector index between pay-as-you-go and fixed, and reset credentials |
| Box | View usage and logs, create, pause, resume and delete boxes; take, restore and delete snapshots |
| Blob | Browse objects, create buckets, delete objects, view stats; reset the bucket token |
Access and credentials
The page holds no credentials. Every action is a tool call back to this server, so OAuth and read-only access apply as they do to the agent; on a read-only connection the page hides write actions. Show credentials fetches secrets only when you open it and never shares them with the model.
Hosts without MCP Apps support show console_redis_keys and console_redis_value to the agent; both are read-only. To leave the console out, list your feature groups without console.
Local server (@upstash/mcp-server)#
A stdio server you run with npx, authenticated with your account email and a Developer API key. Adds Upstash Box tools on top of Redis, QStash, and Workflow. Repository here.
Create an API key from the console — see Developer API → Create an API key. The base command every client uses is:
Add it to your client with the stdio transport, e.g. Claude Code:
See Install by agent for a config snippet for every client.
Readonly API keys are supported. When the server starts with one, it disables every tool that would modify state, such as creating databases, deleting backups, or retrying workflows. Your agent can still read and query your account, but it cannot make changes.
Upstash Box API key (optional)#
For the local server to interact with Upstash Box, the agent needs your Box API key. To avoid pasting it into the chat each time, wire it into the setup — as a CLI flag or an environment variable.
CLI flag
Environment variable
Example prompts#
Redis#
- “Start a free temporary Redis I can experiment with”
- “Create a new Redis database in us-east-1”
- “List my databases sorted by memory usage”
- “Give me the schema of how users are stored in this Redis”
- “Find all session keys expiring in the next hour and show me their payloads”
- “Create a backup of this db, then clear it”
- “Show me throughput spikes during the last 7 days”
QStash & Workflow#
- “Check the QStash logs and figure out why my webhook keeps failing”
- “Find failed workflow runs for user
@ysfk_0xin the last 24 hours” - “Retry the failed workflow run that started 2 hours ago”
- “Summarize what’s in the DLQ right now, grouped by error type”
- “Pause the
daily-reportschedule until Monday”
Vector & Search#
- “List my Vector indexes and show the dimensions of each”
- “Query my Vector index for the 5 nearest neighbours of this text”
- “Upsert these documents into my Search index”
Upstash Box#
- “Spin up a Box, clone this repo, and run the tests”
- “Snapshot this Box and create 5 copies from it, assign each one a GitHub issue”
- “My Box keeps failing to start, check the logs and tell me what’s wrong”
- “Run the app in a Box, screenshot the home page, upload it to Blob and open a PR with the image”
Telemetry#
The local server sends anonymous diagnostic info to Upstash with each request: the MCP server SDK version, your runtime version (Node, Bun, etc.), and basic platform info (OS and architecture). No account data, tool arguments, or results are collected. To opt out, add --disable-telemetry to the args.