@dispersed/mcp-server

Model Context Protocol server for the Dispersed Network compute API. Lets LLM clients (Claude Desktop, Cursor, Claude Code, etc.) launch GPU jobs, manage recipes, check billing, and more.

Exposes 28 tools across jobs, job runs, recipes, GPU registry, SSH keys, billing, and account info.

Install

The server runs via npx - no install step.

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "dispersed": {
      "command": "npx",
      "args": ["-y", "@dispersed/mcp-server"],
      "env": {
        "DISPERSED_PUBLIC_KEY": "pk_...",
        "DISPERSED_SECRET_KEY": "sk_...",
      },
    },
  },
}

Restart your MCP client after updating the config.

Get API keys at https://console.dispersed.com/keys.

Configuration

Credentials resolve in this order (first match wins):

1. Environment variables - DISPERSED_PUBLIC_KEY, DISPERSED_SECRET_KEY, optional DISPERSED_API_URL.

2. Credentials file - $XDG_CONFIG_HOME/dispersed/credentials.json (default: ~/.config/dispersed/credentials.json):

   {
     "publicKey": "pk_...",
     "secretKey": "sk_...",
     "apiUrl": "https://api.dispersed.com"
   }

To create the credentials file interactively:

npx @dispersed/mcp-server setup

The file is written with 0600 permissions.

Tools

Account

| Tool | Description | | --------------------- | -------------------------------------------- | | get_me | Authenticated user info, account UUID, roles | | get_account_balance | Available balance + pending holds | | get_spend_summary | Spending breakdown by category |

Jobs

| Tool | Description | | ------------ | ------------------------------------------------------------- | | list_jobs | List jobs, optionally filtered by status / task type | | get_job | Job details enriched with recent runs | | create_job | Launch a Docker job (BATCH or PERSISTENT) on selected GPU/CPU | | cancel_job | Cancel a running or pending job |

Job Runs

| Tool | Description | | ------------------ | ------------------------------------------------------ | | list_job_runs | List runs, filterable by status / job / node / account | | get_job_run | Run details | | get_job_run_cost | Cost breakdown for a specific run | | cancel_job_run | Cancel a specific run |

Recipes

| Tool | Description | | ----------------------- | ----------------------------------------- | | list_recipes | List public + private recipes | | get_recipe | Recipe details (inspect before cooking) | | cook_recipe | Launch a job from a recipe with overrides | | fork_recipe | Fork an official recipe to a private copy | | create_recipe | Create a private recipe from scratch | | update_recipe | Update private recipe fields | | delete_recipe | Delete a private recipe | | convert_job_to_recipe | Save a job's config as a reusable recipe |

Hardware

| Tool | Description | | ----------- | ------------------------------------------ | | list_gpus | Browse GPU models with VRAM / pricing info |

SSH keys

| Tool | Description | | ---------------- | ---------------------------------- | | list_ssh_keys | List your SSH public keys | | create_ssh_key | Add an SSH public key | | update_ssh_key | Update a key (e.g. set as default) | | delete_ssh_key | Remove a key |

Billing & API keys

| Tool | Description | | --------------------- | ------------------------------------------- | | get_billing_summary | Recent ledger authorizations + transactions | | revoke_api_key | Revoke an API key by UUID |

Setup

| Tool | Description | | ------------------------ | -------------------------------------------- | | get_setup_instructions | Server status + how to configure credentials |

Error handling

Tools return structured errors when the API call fails:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{ \"error\": \"NOT_FOUND\", \"message\": \"...\", \"status\": 404, \"suggestion\": \"...\" }"
    }
  ]
}

The LLM can read error / status / suggestion and respond meaningfully - e.g. authentication errors prompt for credential setup, 404s point at the relevant list_* tool.

Testing

MCP Inspector is a web UI for poking at the server interactively:

npx @modelcontextprotocol/inspector npx -y @dispersed/mcp-server

If you're using env vars instead of the credentials file:

DISPERSED_PUBLIC_KEY=pk_... DISPERSED_SECRET_KEY=sk_... \
  npx @modelcontextprotocol/inspector npx -y @dispersed/mcp-server

Suggested test sequence

1. get_setup_instructions - verify server is running, check config status
2. get_me - confirm auth, note your account_uuid
3. get_account_balance - pass the account_uuid from step 2
4. list_gpus - browse available GPU models
5. list_recipes + get_recipe - inspect a recipe before cooking
6. list_jobs + list_job_runs with status: "RUNNING" - view active work

Built on

• @dispersed/sdk - web-standards TypeScript client for the Dispersed API
• @modelcontextprotocol/sdk - MCP server framework
• zod - tool parameter schemas

License

MIT