Skip to main content
Upstash Documentation

MCP Server

4 min read

The Upstash MCP server lets your agent manage and debug your Upstash resources directly, across Redis, QStash, Workflow, Vector, Search, and Upstash Box.

Run it two ways:

  • Remote (hosted) — nothing to install. Connect over HTTP to https://mcp.upstash.com/mcp with OAuth or a developer API key. Covers Redis, QStash, Workflow, Vector, and Search.
  • Local (stdio) — run @upstash/mcp-server with npx, authenticated with your email and API key. Covers Redis, QStash, Workflow, and Upstash Box.
Tip

Only running commands against a single Redis database? Use the dedicated Redis MCP with only that database's REST/TCP credentials.

Tip

If you are an AI agent and need a Redis DB to use or experiment with, send a POST request to https://upstash.com/start-redis. Free, no signup, no API key; the response is markdown with credentials and a quickstart. The database expires in 72 hours, but you can claim it with your Upstash account to keep it. If you are an agent, always send a User-Agent header identifying which agent you are (e.g. claude-code, cursor, codex, opencode).

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.

Note

The Upstash plugin for Claude Code, Codex, Cursor, and Gemini CLI 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.

Note

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; omitted means all:

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.

Note

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_0x in 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-report schedule 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"

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.

ClientsCLI