# MCP server (/tools/mcp)
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](https://console.shelby.xyz),
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](cursor://anysphere.cursor-deeplink/mcp/install?name=shelby\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAc2hlbGJ5LXByb3RvY29sL21jcEBsYXRlc3QiLCItLWFsbG93LWRpciIsIi9wYXRoL3RvL3lvdXIvZmlsZXMiXSwiZW52Ijp7IlNIRUxCWV9BR0VOVF9LRVkiOiI8eW91ciBhZ2VudCBrZXk%2BIn19)
installs the server with placeholders: replace `` and
`/path/to/your/files` with your own. Or add it to `~/.cursor/mcp.json` yourself:
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"shelby": {
"command": "npx",
"args": [
"@shelby-protocol/mcp@latest",
"--allow-dir",
"/path/to/your/files"
],
"env": {
"SHELBY_AGENT_KEY": ""
}
}
}
}
```
```bash
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](https://console.shelby.xyz/downloads/shelby.mcpb)
and open it. Claude Desktop asks for your agent key and the directories the
server may use.
```toml title="~/.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 = ""
```
```json title="~/.gemini/settings.json"
{
"mcpServers": {
"shelby": {
"command": "npx",
"args": [
"@shelby-protocol/mcp@latest",
"--allow-dir",
"/path/to/your/files"
],
"env": {
"SHELBY_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`:
```bash
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.
```bash
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](/tools/s3-gateway) works with the AWS CLI, boto3, rclone, DuckDB and any
other S3 client.