MCP server

The Shelby MCP server is being published to npm as @shelby-protocol/mcp. Until it is, the npx configurations below won't run. The Claude Desktop extension doesn't need npm.

The Shelby MCP server exposes Shelby storage as tools your agent can call directly, so an agent can manage buckets and upload and download files without you writing any integration code. It acts with an agent key: a key you create in the console, limited to the buckets and access you choose.

Create an agent key

On the Integrations page of the console, create an agent key and choose its:

Name: which agent will use it, so you can tell your keys apart later.
Scope: which buckets the agent can reach.
Access: read and write, or read-only.
Expiry: 30, 60, 90 or 180 days.

Scope	What the agent can reach
Whole organization	Every bucket in your organization. It can create buckets.
Some projects	Every bucket in the projects you check, including new ones. It can create buckets in those projects.
Specific buckets	Only the buckets you check. It can't create buckets.

Access	What the agent can do
Read and write	Everything you can do with those buckets, including uploading files and deleting a bucket and everything in it
Read-only	List and download files. It can't change anything.

Give an agent the least it needs. A read-only key scoped to specific buckets can't delete anything, whatever the agent is asked to do.

The console shows the key once, when you create it. It starts with shelbyagent_. Treat it like a password: anyone who has it gets the access you gave the agent.

Add Shelby to your agent client

Don't put the key in a project-level MCP config. It's easy to commit. Use the one in your home directory, as every setup below does.

--allow-dir names the directories the server may use: uploads read only from them, and downloads write only to them. Replace /path/to/your/files with the absolute path of a directory that exists. To allow more than one, list each after --allow-dir.

Add to Cursor installs the server with placeholders: replace <your agent key> and /path/to/your/files with your own. Or add it to ~/.cursor/mcp.json yourself:

~/.cursor/mcp.json

{
  "mcpServers": {
    "shelby": {
      "command": "npx",
      "args": [
        "@shelby-protocol/mcp@latest",
        "--allow-dir",
        "/path/to/your/files"
      ],
      "env": {
        "SHELBY_AGENT_KEY": "<your agent key>"
      }
    }
  }
}

claude mcp add shelby --scope user \
  --env SHELBY_AGENT_KEY='${SHELBY_AGENT_KEY}' \
  -- npx @shelby-protocol/mcp@latest --allow-dir /path/to/your/files

--scope user saves the server to ~/.claude.json, outside your project. The single quotes save ${SHELBY_AGENT_KEY} itself rather than your key, and Claude Code fills it in from your environment when it starts the server. Export SHELBY_AGENT_KEY in your shell profile, such as ~/.zshrc, before you start Claude Code.

Download the Shelby extension and open it. Claude Desktop asks for your agent key and the directories the server may use.

~/.codex/config.toml

[mcp_servers.shelby]
command = "npx"
args = ["@shelby-protocol/mcp@latest", "--allow-dir", "/path/to/your/files"]
# The first start downloads the package, which can take longer than the 10-second default.
startup_timeout_sec = 60

[mcp_servers.shelby.env]
SHELBY_AGENT_KEY = "<your agent key>"

~/.gemini/settings.json

{
  "mcpServers": {
    "shelby": {
      "command": "npx",
      "args": [
        "@shelby-protocol/mcp@latest",
        "--allow-dir",
        "/path/to/your/files"
      ],
      "env": {
        "SHELBY_AGENT_KEY": "<your agent key>"
      }
    }
  }
}

The npx setups need Node.js 22.12 or later.

Keep the key out of config files

On macOS and Linux, the npx setups can read the key from your system's secret store instead, so no config file holds it. Store it under the service shelby-mcp and the account SHELBY_AGENT_KEY:

security add-generic-password -U -s shelby-mcp -a SHELBY_AGENT_KEY -w

security prompts for the key, so it stays out of your shell history. -U replaces a key you stored before.

secret-tool store --label="Shelby agent key" service shelby-mcp account SHELBY_AGENT_KEY

secret-tool prompts for the key. It needs a running secret service, such as GNOME Keyring.

Then leave SHELBY_AGENT_KEY out of your setup: drop the env block, Codex's [mcp_servers.shelby.env] table, or Claude Code's --env line. A SHELBY_AGENT_KEY environment variable, even one still set to a placeholder, takes precedence over the secret store.

The server reads the key when it starts, so restart your agent client after you replace it. The Claude Desktop extension asks for the key itself, so this doesn't apply to it.

Expiry and revoking

From a week before a key expires, the server tells your agent, so it can remind you. To keep the agent working, create a new key and replace the old one in your config or secret store.

Revoke a key on the Integrations page as soon as an agent no longer needs it, or if it leaks.

The key acts for you. If you leave the organization, it stops working. If you're a Viewer in the organization, it can't make changes.

What it's good for

Agent memory: persistent recall across sessions.
Dataset access: let an agent read training shards directly.
Artifact handoff: write model outputs somewhere durable.

Prefer code?

The S3 API works with the AWS CLI, boto3, rclone, DuckDB and any other S3 client.