
Model Context Protocol (MCP) is an open standard that enables frontier LLMs to produce more relevant responses by safely interacting with external tools and resources where data lives. For more details, go to [MCP Concepts](https://modelcontextprotocol.io/quickstart/server#core-mcp-concepts).

## AgentSphere MCP Server Intro

AgentSphere provides an official MCP server that you can use in your MCP client.

### Tools

The AgentSphere MCP server includes the following four tools:

| Tool Name | Function Description                                  | Parameters                                                                                                                                                                                                   | Return Value                                       |
|----|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| `exec_command` | Executes Linux system commands within the sandbox     | - `cmd` (string): The command to execute                                                                                                                                                                     | Object containing `stdout`, `stderr`, and `success` |
| `get_preview_link` | Retrieves the access URL of a web service in sandbox  | - `port` (int): The port number of the preview link                                                                                                                                                          | Object containing the accessible URL               |
| `upload_files_to_sandbox` | Uploads local files/folders to a specified path in sandbox | - `local_path` (string): Absolute local path<br>- `target_path` (string, optional): Target sandbox directory (default: `/user_uploaded_files/`)                                                              | List of successfully uploaded files or error info  |
| `find_file_path` | Search for the absolute path of a file or directory by name | - `filename` (string): Specifies the name of the file to be searched. Wildcards are supported(e.g., *.py, project*).<br>- `search_path` (string, optional): The starting path for the search or a shortcut option<br>&nbsp;&nbsp;- Indicates a specific directory path (e.g., /Users/username/Desktop/Projects)<br>&nbsp;&nbsp;- Shortcut options available: "desktop" (default), "documents", "downloads", and "home" | The search result contains a list of matched files or directories, with each entry providing details such as the full path, type, size, and last modified time|

## Install AgentSphere MCP Sever in Your MCP Client

### Get AgentSphere API Key

1. Visit [AgentSphere official website](https://www.agentsphere.run/).  

2. Create an account and log in.  

3. Go to the **API Keys** page and copy your **API key**.

### Install `uv`

AgentSphere MCP Server runs via `uv`, a modern, fast Python package & project manager.  

1. Open your **Terminal**.  

2. Install **Homebrew** if it has not been installed yet:

   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```

3. Install `uv` using `Homebrew`:

	```bash
	brew install uv
	```

### Add AgentSphere MCP Server to Claude Code

Run the following command in your terminal to install AgentSphere MCP Server to your Claude Code.

```bash
claude mcp add agentsphere \
  --env AGENTSPHERE_API_KEY="your_api_key_here" \
  -- uvx agentsphere-mcp-server
```

**Note:** Replace `your_api_key_here` with your actual AgentSphere API key.

To verify the installation, run the following command in your terminal:

```bash
claude mcp list
```

**Expected output:** `agentsphere` should appear in the list.


### Add AgentSphere MCP Server to Cursor

1. In your Cursor client, select **Cursor Settings** > **Tools & Integrations** > **New MCP Server**. 

2. Paste the following JSON, and replace `your_api_key_here` with the AgentSphere API key you get.

	```json
	{
  		"mcpServers": {
    	"agentsphere": {
      	"command": "uvx",
      	"args": ["agentsphere-mcp-server"],
      	"env": {
        	"AGENTSPHERE_API_KEY": "your_api_key_here",
      			}
    		}
  		}
	}

### Add AgentSphere MCP Server to Raycast

1. In your Raycast client, type **Install Server** and select the command to open the installation form. 

	![Install mcp server in raycast](/docs/images/raycast-install-mcp.jpg)

2. Add the configurations of AgentSphere MCP Server.

	![Add configurations of AgentSphere MCP Server](/docs/images/raycast-add-agentsphere-mcp.jpg)

	* **name:** Enter a unique name for your server, such as `AgentSphere`.

	* **command:** Enter the command to run the server, such as `uvx`. 

	* **args:** Enter the arguments to pass to the `uvx` command, such as `agentsphere-mcp-server`.

	* **env:** Enter the environment variables required by the server, such as `AGENTSPHERE_API_KEY` and its value.

3. Press the **CMD + Enter** keys to install the AgentSphere MCP Server. 

	![Preview AgentSphere MCP Server in Raycast](/docs/images/raycast-preview-mcp.jpg)

4. Mention AgentSphere (@agentsphere) in your chat to request using AgentSphere sandbox.

	![Mention AgentSphere (@agentsphere) in your Raycast chat to request using AgentSphere sandbox](/docs/images/raycast-use-agentsphere.jpg)


## Work with AgentSphere MCP Sever in Your MCP Client

The following example demonstrates how to connect to AgentSphere MCP server in your Cursor desktop and then generate a live chart for your desired data.

Let's say, you have a file named `product.csv` in your disk and it contains the following data:

| ID | Name                         | Category    | Price | Stock |
|----|------------------------------|-------------|-------|-------|
| 1  | Wireless Mouse               | Electronics | 29.99 | 150   |
| 2  | Bluetooth Keyboard           | Electronics | 49.99 | 80    |
| 3  | USB-C Cable                  | Electronics | 12.99 | 200   |
| 4  | LED Desk Lamp                | Home        | 24.99 | 60    |
| 5  | Stainless Steel Water Bottle | Kitchen     | 19.99 | 100   |
| 6  | Ceramic Mug                  | Kitchen     | 9.99  | 120   |
| 7  | Noise-Cancelling Headphones  | Electronics | 89.99 | 50    |
| 8  | Portable Charger             | Electronics | 34.99 | 90    |
| 9  | Yoga Mat                     | Sports      | 29.99 | 70    |
| 10 | Running Shoes                | Sports      | 59.99 | 40    |
| 11 | Backpack                     | Accessories | 39.99 | 85    |
| 12 | Sunglasses                   | Accessories | 14.99 | 110   |
| 13 | Wireless Earbuds             | Electronics | 69.99 | 65    |
| 14 | Non-Stick Frying Pan         | Kitchen     | 29.99 | 55    |
| 15 | Desk Organizer               | Office      | 15.99 | 130   |
| 16 | Notebook Set                 | Office      | 8.99  | 200   |
| 17 | Smart Watch                  | Electronics | 129.99| 30    |
| 18 | Coffee Maker                 | Kitchen     | 79.99 | 45    |
| 19 | Travel Pillow                | Accessories | 19.99 | 75    |
| 20 | Fitness Tracker              | Electronics | 49.99 | 95    |

1. Launch a new chat in your Cursor client, add the `product.csv` file as context.

2. Call the AgentSphere MCP server to visualize the data inside the table using streamlit in a sandbox.

	![Request AgentSphere MCP Server in your Cursor chat](/docs/images/cursor-chat.png)

    You will get an open URL like `https://<portNumber-UID>.agentsphere.run` and the following is an example of the output.

	![Use AgentSphere to build streamlit output](/docs/images/streamlit-output-map.png)

Explore AgentSphere's official Model Context Protocol (MCP) server, enabling frontier LLMs to safely interact with external tools and data. Learn how to configure AgentSphere as an MCP server for clients like Cursor, Claude Code, and Gemini CLI, and discover examples like generating live data charts within a secure sandbox environment.