# MCP Server

The Upstash MCP server lets your agent manage and debug your Upstash resources directly, across Redis, QStash, Workflow, Vector, Search, and [Upstash Box](/box/overall/quickstart).

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`](https://github.com/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](/redis/sdks/mcp) with only that database's REST/TCP credentials.
</Tip>

<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`).
</Tip>

# Remote server (recommended)

Connect any MCP client over streamable HTTP to:

```
https://mcp.upstash.com/mcp
```

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](/agent-resources/clients).

<Tabs>
  <Tab title="Claude Code">
    ```sh
    claude mcp add --scope user --transport http upstash https://mcp.upstash.com/mcp
    ```
    Then run `/mcp` → **Authenticate**.
  </Tab>
  <Tab title="Cursor">
    Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
    ```json
    {
      "mcpServers": {
        "upstash": { "url": "https://mcp.upstash.com/mcp" }
      }
    }
    ```
  </Tab>
  <Tab title="OpenCode">
    Edit `~/.config/opencode/opencode.json` (or a project `opencode.json`):
    ```json
    {
      "mcp": {
        "upstash": {
          "type": "remote",
          "url": "https://mcp.upstash.com/mcp",
          "enabled": true
        }
      }
    }
    ```
  </Tab>
  <Tab title="OpenAI Codex">
    Add to `~/.codex/config.toml` (or `.codex/config.toml`):
    ```toml
    [mcp_servers.upstash]
    url = "https://mcp.upstash.com/mcp"
    ```
  </Tab>
</Tabs>

<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](/agent-resources/clients).
</Note>

## 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`:

```sh
claude mcp add --scope user --transport http upstash https://mcp.upstash.com/mcp \
  --header "Authorization: Bearer you@example.com:YOUR_API_KEY"
```

Create a key from the console — see [Developer API → Create an API key](/devops/developer-api/introduction#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.
</Note>

## 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:

```
https://mcp.upstash.com/mcp?features=redis,qstash_workflow
```

# 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](/box/overall/quickstart) tools on top of Redis, QStash, and Workflow. Repository [here](https://github.com/upstash/mcp-server).

Create an API key from the console — see [Developer API → Create an API key](/devops/developer-api/introduction#create-an-api-key). The base command every client uses is:

```bash
npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY
```

Add it to your client with the stdio transport, e.g. Claude Code:

```sh
claude mcp add --transport stdio upstash -- npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY
```

See [Install by agent](/agent-resources/clients) 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.
</Note>

## Upstash Box API key (optional)

For the local server to interact with [Upstash Box](/box/overall/quickstart), 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.

<AccordionGroup>
  <Accordion title="CLI flag">
    ```json
    {
      "mcpServers": {
        "upstash": {
          "command": "npx",
          "args": [
            "-y", "@upstash/mcp-server@latest",
            "--email", "YOUR_EMAIL",
            "--api-key", "YOUR_API_KEY",
            "--box-api-key", "YOUR_BOX_API_KEY"
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Environment variable">
    ```json
    {
      "mcpServers": {
        "upstash": {
          "command": "npx",
          "args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"],
          "env": {
            "UPSTASH_BOX_API_KEY": "YOUR_BOX_API_KEY"
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

# 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.