Spheron Protocol MCP server for AI agents

The Spheron Network MCP plugin integrates with Spheron Protocol SDK to provide compute deployment and management capabilities directly through Claude. This Model Context Protocol (MCP) server lets you deploy and manage compute resources using simple natural language commands within Claude.

Installation Options

Docker Installation (Recommended)

The easiest way to install the Spheron MCP plugin is using Docker:

# Pull the Docker image
docker pull saurrx/spheron-mcp:latest

Manual Installation

If you prefer to install from source:

# Clone the repository
git clone https://github.com/spheronFdn/spheron-mcp-plugin.git

# Navigate to the project directory
cd spheron-mcp-plugin

# Navigate to the server directory
cd spheron-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration Setup

For VS Code

Create the MCP settings directory and file:

# For Linux:
mkdir -p ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# For macOS:
mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# For Windows (create the file at):
# %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Add the configuration using Docker:

{
  "mcpServers": {
    "spheron": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SPHERON_PRIVATE_KEY",
        "-e",
        "SPHERON_NETWORK",
        "-e",
        "PROVIDER_PROXY_URL",
        "-e",
        "YAML_API_URL",
        "saurrx/spheron-mcp:latest"
      ],
      "env": {
        "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
        "SPHERON_NETWORK": "testnet",
        "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
        "YAML_API_URL": "http://149.56.15.95:8080/generate"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Or if using the Node.js installation:

{
  "mcpServers": {
    "spheron": {
      "command": "node",
      "args": [
        "/absolute/path/to/spheron-mcp-plugin/mcp-server/build/index.js"
      ],
      "env": {
        "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
        "SPHERON_NETWORK": "testnet",
        "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
        "YAML_API_URL": "http://149.56.15.95:8080/generate"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

For Claude Desktop

Create the configuration file:

# For macOS:
mkdir -p ~/Library/Application\ Support/Claude/
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows (create the file at):
# %APPDATA%\Claude\claude_desktop_config.json

# For Linux:
mkdir -p ~/.config/Claude/
touch ~/.config/Claude/claude_desktop_config.json

Add the same configuration JSON as shown above for VS Code.

For Cursor

Create the configuration file:

# For macOS:
mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# For Windows (create the file at):
# %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

# For Linux:
mkdir -p ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add the same configuration JSON as shown above for VS Code.

Required Environment Variables

Make sure to set these variables in your configuration:

SPHERON_PRIVATE_KEY: Your Spheron private key
SPHERON_NETWORK: Set to "testnet" or "mainnet"
PROVIDER_PROXY_URL: Usually "https://provider-proxy.sphn.xyz"
YAML_API_URL: Usually "http://149.56.15.95:8080/generate"

Using the MCP Plugin

Once configured, you can use the plugin directly through Claude with natural language commands:

Deploying Compute Resources

To deploy a compute resource, you can provide a YAML configuration directly:

Deploy this compute configuration:
version: "1.0"

services:
  py-cuda:
    image: quay.io/jupyter/pytorch-notebook:cuda12-pytorch-2.4.1
    expose:
      - port: 8888
        as: 8888
        to:
          - global: true
    env:
      - JUPYTER_TOKEN=sentient
profiles:
  name: py-cuda
  duration: 2h
  mode: provider
  tier:
    - community
  compute:
    py-cuda:
      resources:
        cpu:
          units: 8
        memory:
          size: 16Gi
        storage:
          - size: 200Gi
        gpu:
          units: 1
          attributes:
            vendor:
              nvidia:
                - model: rtx4090
  placement:
    westcoast:
      attributes:
        region: us-central
      pricing:
        py-cuda:
          token: CST
          amount: 10

deployment:
  py-cuda:
    westcoast:
      profile: py-cuda
      count: 1

Or simply ask Claude in natural language:

Deploy a jupyter notebook on Spheron

Checking Wallet Balance

What's my CST balance on Spheron?

Getting Deployment URLs

Show me the URLs for my deployment with lease ID 12345

Getting Deployment Details

Get details for lease ID 12345

The MCP plugin will handle these requests and return relevant information directly within your Claude conversation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "spheron" '{"command":"node","args":["/absolute/path/to/spheron-mcp-plugin/mcp-server/build/index.js"],"env":{"SPHERON_PRIVATE_KEY":"your-spheron-private-key","SPHERON_NETWORK":"testnet","PROVIDER_PROXY_URL":"https://provider-proxy.sphn.xyz","YAML_API_URL":"http://149.56.15.95:8080/generate"},"disabled":false,"autoApprove":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "spheron": {
            "command": "node",
            "args": [
                "/absolute/path/to/spheron-mcp-plugin/mcp-server/build/index.js"
            ],
            "env": {
                "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
                "SPHERON_NETWORK": "testnet",
                "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
                "YAML_API_URL": "http://149.56.15.95:8080/generate"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "spheron": {
            "command": "node",
            "args": [
                "/absolute/path/to/spheron-mcp-plugin/mcp-server/build/index.js"
            ],
            "env": {
                "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
                "SPHERON_NETWORK": "testnet",
                "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
                "YAML_API_URL": "http://149.56.15.95:8080/generate"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect