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).

## Overview

AgentSphere provides an official MCP server that you can use in your MCP client.

### Tools


**Sandbox Management**

| Tool Name | Description | Parameters | Result Description |
|-----------|-------------|------------|-------------------|
| sandbox_create | Create a new sandbox instance | - `template` (string, optional): Sandbox template name, defaults to "agentsphere-code-interpreter-v1" - `timeout` (int, optional): Timeout in seconds, defaults to 43200 (12 hours) - `metadata` (object, optional): Custom metadata - `envs` (object, optional): Environment variables | Object containing sandbox_id, template, envd_version, etc. |
| sandbox_is_running | Check if sandbox is running | - `sandbox_id` (string): Unique sandbox identifier | Boolean: true if running, false if not |
| sandbox_settimeout | Dynamically adjust sandbox lifetime/expiration timeout | - `timeout` (int): Timeout duration in seconds - `sandbox_id` (string, optional): Sandbox ID | Object containing sandbox_id, timeout, timestamp, etc. |
| sandbox_get_logs | Get sandbox logs | - `start` (int, optional): Starting position, defaults to 0 - `limit` (int, optional): Maximum log entries, defaults to 1000 - `sandbox_id` (string, optional): Sandbox ID | Object containing logs list, total count, has_more flag, etc. |

**Command Execution Tools**

| Tool Name | Description | Parameters | Result Description |
|-----------|-------------|------------|-------------------|
| exec_command | Execute Linux commands in sandbox | - `cmd` (string): Command to execute - `sandbox_id` (string, optional): Sandbox ID | Object containing stdout, stderr, and success status |

**Network Service Tools**

| Tool Name | Description | Parameters | Result Description |
|-----------|-------------|------------|-------------------|
| get_preview_link | Get access URL for services running in sandbox | - `port` (int): **Required**, service listening port number - `sandbox_id` (string, optional): Target sandbox ID | Object containing the preview URL |

**Filesystem Tools**

| Tool Name | Description | Parameters | Result Description |
|-----------|-------------|------------|-------------------|
| file_read | Read file content from sandbox | - `path` (string): File path in sandbox (e.g., "/home/user/test.txt") - `sandbox_id` (string, optional): Sandbox ID | File content as string, empty string if file doesn't exist |
| sandbox_file_write | Write content to file in sandbox | - `path` (string): File path - `content` (string): Content to write - `sandbox_id` (string, optional): Sandbox ID | Object containing path, name, type, etc. |
| sandbox_mkdir | Create directory in sandbox | - `path` (string): Directory path (e.g., "/home/user/my/nested/dir") - `sandbox_id` (string, optional): Sandbox ID | Object containing path, created status, etc. |
| sandbox_list_dir | List entries in directory | - `path` (string): Directory path to list - `sandbox_id` (string, optional): Sandbox ID | Object containing entries list, file/directory counts, etc. |
| sandbox_dir_exist | Check if file or directory exists | - `path` (string): Path to check - `sandbox_id` (string, optional): Sandbox ID | Boolean: true if exists, false if not |
| upload_files_to_sandbox | Upload local files or folders to sandbox | - `local_path` (string): Local absolute path - `target_path` (string, optional): Target path in sandbox, defaults to /user_uploaded_files/ - `sandbox_id` (string, optional): Sandbox ID | List of successfully uploaded files or error information |
| find_file_path | Search for absolute paths of files or directories by name | - `filename` (string): File name to search (supports wildcards like "*.py", "project*") - `search_path` (string, optional): Search starting path or shortcut ("desktop", "documents", "downloads", "home"), defaults to desktop | List of found files/directories with complete path, type, size, modification time, etc. |

**PTY Terminal Tools**

| Tool Name | Description | Parameters | Result Description |
|-----------|-------------|------------|-------------------|
| pty_create | Cross-platform terminal launch and agentsphere CLI command execution | - `sandbox_id` (string, optional): Sandbox ID | Object containing platform, process_id, command, etc. |
| pty_send_input | Send input command to PTY sandbox | - `input` (string): Input command content to send to sandbox - `sandbox_id` (string, optional): Sandbox ID | Object containing sandbox_id, input, timestamp, etc. |
| pty_get_latest_output | Get latest output from sandbox PTY | - `sandbox_id` (string, optional): Sandbox ID - `timeout` (float, optional): Timeout for waiting output response (seconds), defaults to 2.0 | Object containing output, has_output, timestamp, etc. |
| pty_kill | Close PTY connection and cleanup client | - `sandbox_id` (string): sandbox ID to kill | Object containing sandbox_id, timestamp, etc. |

### Configurations

The configurations of AgentSphere MCP server is detailed as follows. Replace `your_api_key_here` with the actual value of your AgentSphere API key.

	```json
	{
 		"mcpServers": {
 	"agentsphere": {
 	"command": "uvx",
 	"args": ["agentsphere-mcp-server@latest"],
 	"env": {
 	"AGENTSPHERE_API_KEY": "your_api_key_here"
 			}
 		}
 		}
	}
	```

## Install AgentSphere MCP Sever

### 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 to Claude Code

1. Run the following command in your terminal to install AgentSphere MCP Server to your Claude Code.

```bash
claude mcp add agentsphere --scope user \
 --env AGENTSPHERE_API_KEY="your_api_key_here" \
 -- uvx agentsphere-mcp-server@latest
```

**Note:** 

- Replace `your_api_key_here` with your actual AgentSphere API key.

- Using `--scope user` means the AgentSphere MCP Server is available to you across all projects. To share with others in a project, use `--scope project`. For more information, see [Anthropic Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).


2. To verify the installation, run the following command in your terminal:

```bash
claude mcp list
```

**Expected output:**

```bash
Checking MCP server health...
agentsphere: uvx agentsphere-mcp-server - ✓ Connected
```

### Add 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@latest"],
 	"env": {
 	"AGENTSPHERE_API_KEY": "your_api_key_here"
 			}
 		}
 		}
	}
	```

### Add 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@latest`.

	* **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)


## Use AgentSphere MCP Sever

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 Raycast, and discover examples like generating live data charts within a secure sandbox environment.