Docs/ AI Assistant/ MCP Server

MCP Server

Connect Claude Desktop, Claude Code, Cursor, or any MCP-compatible client to sh0 and manage your deployments through natural language.

What is MCP

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. Instead of copy-pasting terminal output into a chat window, MCP lets your AI assistant interact with sh0 directly -- listing apps, reading logs, triggering deploys, and diagnosing issues.

sh0 includes a built-in MCP server exposed at POST /api/v1/mcp using the Streamable HTTP transport. Any client that supports MCP can connect to it with nothing more than a URL and an API key.

Connecting Claude Desktop

Add the following to your Claude Desktop configuration file at ~/.claude/claude_desktop_config.json:

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

Replace your-server.com with your sh0 server address and sh0_your_api_key with a valid API key. Restart Claude Desktop to pick up the new configuration.

Connecting Claude Code

For Claude Code (the CLI), add the same configuration to ~/.claude.json under the mcpServers key:

~/.claude.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

Once configured, Claude Code will automatically discover and use sh0 tools when relevant to your prompts.

Connecting Cursor

In Cursor, open Settings → MCP and add a new server with the same JSON configuration:

Cursor MCP Settings

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

The configuration is identical across all three clients. Any MCP-compatible tool that supports the Streamable HTTP transport will work with the same URL and credentials.

Tip

You can test your MCP connection with:

curl -X POST https://your-server/api/v1/mcp -H 'Authorization: Bearer sh0_xxx' -H 'Content-Type: application/json' -d 'undefined,"clientInfo":undefined}}'

API Key Scopes

API keys control which tools the AI assistant can access. Each key is assigned a scope that determines its permissions:

Scope	Tools	Description
`read`	The 45 read tools	List and inspect apps, services, domains, logs, and metrics. No modifications allowed.
`deploy`	Read + deploy	Everything in read, plus deploy, roll back, restart, start, stop and scale apps that already exist. Cannot create or delete apps, change their configuration or domains, run commands, or create API keys.
`admin`	All 106 tools	Full access: creating apps (`create_app`, `upload_app`, `deploy_template`, `deploy_compose`), the sandbox tools, server settings, user management, backups and destructive actions. No key, not even an admin key, can create another API key.

To create an API key, navigate to Settings → API Keys in the dashboard. Choose the scope based on what you need the AI to do. For day-to-day work on apps that already exist, deploy is the right balance of capability and safety. Keys created before v1.10.2 with the standard scope are read as deploy.

Warning

Use the admin scope only when the AI needs to create or delete apps, change configuration or run commands. For deploying and restarting existing apps, deploy is recommended.

Auto-Discovery

All 106 tools are automatically discovered by MCP clients. No manual tool registration is needed. When a client connects, it calls the tools/list method, and sh0 responds with the complete tool catalog -- names, descriptions, and JSON Schema parameter definitions.

The list is the same for every key: tools/list returns all 106 tools (45 read, 45 write, 16 destructive). The key's scope is checked when a tool is called: a read key that calls a write tool gets “API key scope 'read' cannot execute 'write' risk tools”.

Session Management

The MCP server uses sessions to maintain state across multiple requests within a conversation. Each session is identified by a UUID v4 returned in the Mcp-Session-Id response header after the initialize call.

Clients must include this header in all subsequent requests. Session details:

ID format: UUID v4 (e.g., a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d)
TTL: 1 hour of inactivity
Eviction: Lazy -- expired sessions are cleaned up when new sessions are created
Scope: Each session inherits the API key scope used during initialization

Troubleshooting

Common issues when connecting to the MCP server:

Connection refused

Verify that the sh0 server is running and the port is accessible. If connecting from outside the local network, ensure your firewall allows inbound traffic on the sh0 API port (default 9000).

HTTPS required

MCP clients typically require HTTPS for remote connections. If you are accessing sh0 over the internet, make sure your server has a valid SSL certificate. Local connections to localhost or 127.0.0.1 may work over plain HTTP.

Tools not appearing

If the connection succeeds but no tools appear, the API key scope may be too narrow for the tools you expect. Check that the key has the correct scope in Settings → API Keys. Also verify that the Authorization header is formatted correctly as Bearer sh0_....

Session expired

Sessions expire after 1 hour of inactivity. If you receive a session error, the client should automatically re-initialize. If it does not, restart the MCP client to create a new session.

Getting Started

AI Sandbox