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 /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/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/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/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/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`	37 tools	List and inspect apps, services, domains, logs, and metrics. No modifications allowed.
`standard`	Read + write	Everything in read, plus create apps, trigger deploys, update environment variables, and manage domains.
`admin`	All 103 tools	Full access including server settings, user management, backup operations, and destructive actions.

To create an API key, navigate to Settings → API Keys in the dashboard. Choose the appropriate scope based on what you need the AI to do. For most development workflows, standard provides the right balance of capability and safety.

Warning

Use the admin scope only when the AI needs to perform server-level operations. For day-to-day development, standard is recommended.

Auto-Discovery

All 103 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 tool list is filtered based on the API key scope. A read-scoped key will only see the 37 read-only tools, while an admin key sees all 103.

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