@gravytraining/dataswap-mcp

@gravytraining/dataswap-mcp

MCP server for DataSwap — move notes, snippets and context between Claude environments.

It runs locally and talks to your own DataSwap deployment over HTTPS. Nothing is stored on this machine and the package grants access to nothing without a credential you mint yourself.

Before you start

You need a DataSwap deployment of your own and a credential from it:

1. Deploy DataSwap and note its URL, e.g. https://dataswap.vercel.app.

2. Visit /admin, sign in with your admin key, and mint a credential. Tick the permissions for the capabilities you want:

   Permission	Unlocks
   read	dataswap_get, dataswap_list, dataswap_search
   write	dataswap_save, dataswap_update, dataswap_delete
   files	dataswap_save_file, dataswap_get_file
   email:draft	dataswap_draft_email

   All four is the usual answer. A credential missing one is not broken — the capability it covers refuses with a message naming the permission — but you will find out the first time you try to save a screenshot, which is a worse moment than now.

   Do not tick admin. It grants the ability to list and revoke every other credential, which is not something a config file on a laptop should be able to do. There is no email:send to tick: sending is approved by a human at /admin/drafts and by nothing else.

3. Copy the token. It is shown once and cannot be retrieved afterwards.

Setup

Claude Code

claude mcp add dataswap \
  --env DATASWAP_URL=https://your-deployment.vercel.app \
  --env DATASWAP_TOKEN=dsw_your_token_here \
  --env DATASWAP_CLIENT_NAME=claude-code-personal \
  -- npx -y @gravytraining/dataswap-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "dataswap": {
      "command": "npx",
      "args": ["-y", "@gravytraining/dataswap-mcp"],
      "env": {
        "DATASWAP_URL": "https://your-deployment.vercel.app",
        "DATASWAP_TOKEN": "dsw_your_token_here",
        "DATASWAP_CLIENT_NAME": "claude-desktop"
      }
    }
  }
}

Restart the client. That is the whole setup — there is no sign-in step and no browser flow.

Configuration

Variable	Required	Purpose
DATASWAP_URL	yes	Your deployment's address. Must be https, except for localhost.
DATASWAP_TOKEN	yes	A credential minted at /admin. Sent with every request.
DATASWAP_CLIENT_NAME	no	Recorded on entries so you can tell which machine wrote one. Defaults to mcp.

Neither required variable has a default. If either is missing the server exits at startup naming the one that is missing, so your client reports it when it connects rather than when you first try to use it.

What it can do

Capability	Needs
dataswap_save	write
dataswap_get	read
dataswap_list	read
dataswap_search	read
dataswap_update	write
dataswap_delete	write

Your credential's permissions decide which of these work. A read-only credential can list and search and will be refused on the rest.

dataswap_update replaces an entry rather than merging into it — fields you do not supply return to their defaults. Say what you want kept.

Versions

npx -y fetches the latest version each time your client launches the server, so you get fixes without touching your configuration.

To pin a version, when you would rather it not change under you:

"args": ["-y", "@gravytraining/dataswap-mcp@0.1.0"]

To roll back, pin the previous version the same way and restart the client. Nothing is stored locally, so moving between versions needs no cleanup.

When something goes wrong

Failures come back as one of four kinds, so you know where to look:

Kind	What it means	Where to look
configuration	A required variable is missing or unusable	Your client's MCP settings
transport	The deployment could not be reached	The deployment, or this machine's network
authorisation	The credential was rejected or lacks a permission	Mint a new one at /admin
request	The arguments were rejected	The message names the field

A revoked credential reports as authorisation, never as transport — so you are not sent to check a deployment that is perfectly healthy.

The server writes diagnostics to stderr. Your client usually surfaces these in its MCP logs.

Privacy

The credential is sent to your deployment and nowhere else. It is never logged, never written to disk by this package, and never included in an error message.

Licence

MIT