### Install Dependencies and Run Development Server

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Installs project dependencies, builds runtime images, and starts the development server. Ensure Bun 1.1+ and Podman (rootless) are installed.

```bash
bun install
bun run build:runtime-images
bun run dev
```

--------------------------------

### Start Development Server with Bun

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/CONTRIBUTING.md

Starts the project in development mode using Bun. This is typically done after installing dependencies and building images.

```bash
bun run dev
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/CONTRIBUTING.md

Installs project dependencies using Bun. Ensure Bun is installed before running.

```bash
bun install
```

--------------------------------

### Install Dependencies and Restart Service

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/DEPLOYMENT.md

Installs Node.js dependencies using Bun, reloads the systemd user daemon, and restarts the mcp-as-a-service. It also checks if the service is active.

```bash
ssh ubuntu@<host> \
  'set -e
  cd ~/mcp-as-a-service
  export PATH="$HOME/.bun/bin:$PATH"
  bun install
  systemctl --user daemon-reload
  systemctl --user restart mcp-as-a-service.service
  systemctl --user is-active mcp-as-a-service.service
'
```

--------------------------------

### Start Production Server

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Starts the MCP-as-a-Service in production mode. The default port is 8787, which can be overridden by the PORT environment variable.

```bash
bun run start
```

--------------------------------

### Install Podman and Dependencies on Ubuntu

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/TROUBLESHOOTING.md

Install Podman and necessary dependencies like uidmap, slirp4netns, fuse-overlayfs, and apparmor on Ubuntu systems.

```bash
sudo apt-get update
sudo apt-get install -y podman uidmap slirp4netns fuse-overlayfs apparmor apparmor-utils
```

--------------------------------

### GET /package/:packageName/sse

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Starts or attaches to an MCP server backed by a package, using Server-Sent Events (SSE).

```APIDOC
## GET /package/:packageName/sse

### Description
Starts or attaches to an MCP server backed by a package, using Server-Sent Events (SSE).

### Method
GET

### Endpoint
/package/:packageName/sse

### Query Parameters
- **COINGECKO_ENVIRONMENT** (string) - Optional - Specifies the environment.
- **COINGECKO_DEMO_API_KEY** (string) - Optional - Demo API key for authentication.

### Request Example
```bash
curl -N "http://127.0.0.1:8787/package/%40coingecko%2Fcoingecko-mcp/sse?COINGECKO_ENVIRONMENT=demo&COINGECKO_DEMO_API_KEY=test"
```
```

--------------------------------

### Start MCP Service

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Start the mcp-as-a-service if it has been stopped. This command is used to initiate the service, for example, after a system reboot or manual stop.

```bash
ssh ubuntu@<host> 'systemctl --user start mcp-as-a-service.service'
```

--------------------------------

### Install Podman Prerequisites on Ubuntu

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Installs necessary packages for running Podman in rootless mode on Ubuntu. Includes Podman, uidmap, slirp4netns, fuse-overlayfs, and AppArmor utilities.

```bash
sudo apt-get update
sudo apt-get install -y podman uidmap slirp4netns fuse-overlayfs apparmor apparmor-utils
podman --version
podman info | grep rootless
```

--------------------------------

### Verify Podman Installation and Configuration

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/TROUBLESHOOTING.md

Check if Podman is installed and if it's configured for rootless mode. This is crucial for the RUNTIME_NOT_AVAILABLE error.

```bash
podman --version
```

```bash
podman info | grep rootless
```

--------------------------------

### GET /

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Retrieves service metadata, protocol information, and usage hints.

```APIDOC
## GET /

### Description
Retrieves service metadata, protocol information, and usage hints.

### Method
GET

### Endpoint
/

```

--------------------------------

### Connect to Package-Backed Server via SSE

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Example using curl to establish a Server-Sent Events (SSE) connection to a package-backed MCP server. Query parameters are used to specify the environment and API key.

```bash
curl -N "http://127.0.0.1:8787/package/%40coingecko%2Fcoingecko-mcp/sse?COINGECKO_ENVIRONMENT=demo&COINGECKO_DEMO_API_KEY=test"
```

--------------------------------

### Build Runtime Images with Bun

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/CONTRIBUTING.md

Builds the runtime images for the project using Bun. This command is part of the development setup.

```bash
bun run build:runtime-images
```

--------------------------------

### GET /servers

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Lists active MCP runtime processes and their associated client counts.

```APIDOC
## GET /servers

### Description
Lists active MCP runtime processes and their associated client counts.

### Method
GET

### Endpoint
/servers

```

--------------------------------

### Initialize MCP Service via JSON-RPC

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Example using curl to send an initialization request to the MCP service's JSON-RPC endpoint. Ensure the Content-Type is set to application/json.

```bash
curl -X POST http://127.0.0.1:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

--------------------------------

### Start SSE Stream

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Initiates a Server-Sent Events (SSE) stream from the firecrawl-mcp package. Requires a firecrawlApiKey for authentication.

```bash
curl -N "http://127.0.0.1:8787/package/firecrawl-mcp/sse?firecrawlApiKey=YOUR_KEY"
```

--------------------------------

### MCP Health Check Response Example

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Example JSON response indicating the health status of the MCP service, its protocol version, initialization state, and execution mode.

```json
{
  "status": "healthy",
  "mcp": { "protocolVersion": "2024-11-05", "initialized": false },
  "execution": { "mode": "podman" }
}
```

--------------------------------

### GET /mcp/capabilities

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Retrieves the current capabilities and status of the MCP.

```APIDOC
## GET /mcp/capabilities

### Description
Retrieves the current capabilities and status of the MCP.

### Method
GET

### Endpoint
/mcp/capabilities

```

--------------------------------

### Package Message Acceptance Response

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Example JSON response indicating that a message sent to a package runtime has been accepted.

```json
{ "accepted": true }
```

--------------------------------

### Send JSON-RPC Message to Package Runtime

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Example using curl to send a JSON-RPC payload to the runtime process of a specific package. The Content-Type must be application/json.

```bash
curl -X POST "http://127.0.0.1:8787/package/%40coingecko%2Fcoingecko-mcp/messages?COINGECKO_ENVIRONMENT=demo&COINGECKO_DEMO_API_KEY=test" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

--------------------------------

### Restart MCP Service

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Restart the mcp-as-a-service if it becomes unresponsive or requires a refresh. This command will stop and then start the service.

```bash
ssh ubuntu@<host> 'systemctl --user restart mcp-as-a-service.service'
```

--------------------------------

### Send JSON-RPC Message via HTTP/SSE

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Sends a JSON-RPC initialization message to the firecrawl-mcp package endpoint. This is used to establish communication after starting the SSE stream.

```bash
curl -X POST "http://127.0.0.1:8787/package/firecrawl-mcp/messages?firecrawlApiKey=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

--------------------------------

### Check Server Status Endpoint

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Query the /servers endpoint to get information about the servers managed by mcp-as-a-service. This helps in understanding the service's current server inventory.

```bash
ssh ubuntu@<host> 'curl -sS http://127.0.0.1:8787/servers'
```

--------------------------------

### GET /health

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Checks the health status of the service. Includes details about the MCP protocol and execution environment.

```APIDOC
## GET /health

### Description
Checks the health status of the service. Includes details about the MCP protocol and execution environment.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service.
- **mcp** (object) - MCP protocol details.
  - **protocolVersion** (string) - The protocol version.
  - **initialized** (boolean) - Indicates if the MCP is initialized.
- **execution** (object) - Execution environment details.
  - **mode** (string) - The execution mode.

### Response Example
{
  "status": "healthy",
  "mcp": { "protocolVersion": "2024-11-05", "initialized": false },
  "execution": { "mode": "podman" }
}
```

--------------------------------

### Bypass Cache for Package Requests Rule

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Set up a rule to bypass caching for all requests starting with '/package/'. This ensures that package-related operations always fetch fresh data from the origin server.

```text
Rule Name: No Cache Package Requests
Match: URI Path starts with "/package/"
Cache Level: Bypass
```

--------------------------------

### Custom Firewall Rule: Geographic Restrictions

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Configure a custom firewall rule to restrict access based on geographic location. This example blocks all countries except the US, DE, GB, CA, AU, FR, NL, and JP. Adjust the country codes as needed.

```javascript
// Allow only specific countries (adjust as needed)
not (ip.geoip.country in {"US" "DE" "GB" "CA" "AU" "FR" "NL" "JP"})
```

--------------------------------

### Check MCP Service Log Files

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/TROUBLESHOOTING.md

Examine the combined and error log files for the mcp-as-a-service to diagnose startup issues.

```bash
tail -n 200 ~/mcp-as-a-service/combined.log
```

```bash
tail -n 200 ~/mcp-as-a-service/error.log
```

--------------------------------

### Deploy Workspace to Server

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/DEPLOYMENT.md

Archives the current workspace, excluding specified files and directories, and transfers it to the server. Run this command from your local repository root.

```bash
tar --exclude='.git' --exclude='node_modules' --exclude='combined.log' --exclude='error.log' \
  --exclude='.DS_Store' -czf - AGENTS.md README.md package.json bun.lock tsconfig.json \
  ecosystem.config.cjs src test scripts docs nginx.conf .env.example \
| ssh ubuntu@<host> 'cd ~/mcp-as-a-service && tar -xzf -'
```

--------------------------------

### Run All Tests with Bun

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/CONTRIBUTING.md

Executes all tests for the project using Bun. This command should be run to ensure code changes do not break existing functionality.

```bash
bun test
```

--------------------------------

### Configure Podman for Caching

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/TROUBLESHOOTING.md

Ensure the service has PODMAN_READ_ONLY set to false for dynamic npx bootstrapping to allow cache writes.

```bash
PODMAN_READ_ONLY=false
```

--------------------------------

### Check Runtime Environment Variables

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/DEPLOYMENT.md

Verifies the runtime environment variables for the mcp-as-a-service, specifically checking the PORT, NODE_ENV, and PODMAN_READ_ONLY settings.

```bash
ssh ubuntu@<host> 'systemctl --user show mcp-as-a-service.service -p Environment'
```

--------------------------------

### Direct MCP Initialization via HTTP POST

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Sends a JSON-RPC initialization message directly to the MCP endpoint. This bypasses the package-specific bridge and is used for direct MCP communication.

```bash
curl -X POST https://mcp.llmbase.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

--------------------------------

### Run MCP Protocol Compliance Tests

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/MCP_COMPLIANCE.md

Execute the specific integration test file for MCP protocol compliance using bun test.

```bash
bun test test/integration/mcp-protocol-compliance.test.ts
```

--------------------------------

### Server Capabilities

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Retrieves the server's capabilities and status.

```APIDOC
## GET /mcp/capabilities

### Description
Retrieves the server's capabilities and status.

### Method
GET

### Endpoint
/mcp/capabilities

```

--------------------------------

### Check MCP Service Status and Logs

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/TROUBLESHOOTING.md

Use these commands to check the status of the mcp-as-a-service and view its recent logs.

```bash
systemctl --user status --no-pager mcp-as-a-service.service
```

```bash
journalctl --user -u mcp-as-a-service.service -n 100 --no-pager
```

--------------------------------

### Test Caching

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Perform a HEAD request to the root path ('/') to test the caching configuration. This checks if the response headers indicate proper caching behavior.

```bash
# Test caching
curl -I "https://mcp.llmbase.ai/"
```

--------------------------------

### Basic Debugging with Cloudflare Trace

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Use the `curl` command with the `CF-RAY` header to perform a basic trace of a request to the '/health' endpoint. This helps in debugging by showing the Cloudflare Ray ID.

```bash
curl -H "CF-RAY: on" https://mcp.llmbase.ai/health
```

--------------------------------

### View Combined Log File

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Tail the last 100 lines of the combined log file for mcp-as-a-service. This provides a consolidated view of service output.

```bash
ssh ubuntu@<host> 'tail -n 100 ~/mcp-as-a-service/combined.log'
```

--------------------------------

### Test Security Headers with cURL

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Use this command to test the security headers of your MCP-as-a-Service endpoint. Look for expected security headers in the output.

```bash
curl -I "https://mcp.llmbase.ai/"
```

--------------------------------

### Service Metadata

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Retrieves service metadata and usage hints.

```APIDOC
## GET /

### Description
Retrieves service metadata and usage hints.

### Method
GET

### Endpoint
/

```

--------------------------------

### Add Firecrawl MCP Package to Claude Desktop

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Configures Claude Desktop to use the firecrawl-mcp package hosted by MCP-as-a-Service. Uses HTTP transport.

```bash
claude mcp add firecrawl \
  'https://mcp.llmbase.ai/package/firecrawl-mcp/sse?firecrawlApiKey=YOUR_KEY' \
  -t http
```

--------------------------------

### Enable Service Lingering for Persistence

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/TROUBLESHOOTING.md

Enable lingering for a user to ensure their services remain active after reboot. Replace 'ubuntu' with the actual username.

```bash
sudo loginctl enable-linger ubuntu
```

```bash
loginctl show-user ubuntu -p Linger
```

--------------------------------

### POST /mcp

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Serves as the JSON-RPC 2.0 endpoint for interacting with the MCP. Used for methods like 'initialize'.

```APIDOC
## POST /mcp

### Description
Serves as the JSON-RPC 2.0 endpoint for interacting with the MCP. Used for methods like 'initialize'.

### Method
POST

### Endpoint
/mcp

### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (number) - Required - The ID of the request.
- **method** (string) - Required - The name of the method to call.
- **params** (object) - Optional - Parameters for the method call.
  - **protocolVersion** (string) - Required - The protocol version.
  - **capabilities** (object) - Optional - Client capabilities.
  - **clientInfo** (object) - Optional - Client information.
    - **name** (string) - Required - The client name.
    - **version** (string) - Required - The client version.

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test",
      "version": "1.0"
    }
  }
}

```

--------------------------------

### Check MCP Service Status

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Use this command to check the current status of the mcp-as-a-service. Ensure the service is running as expected.

```bash
ssh ubuntu@<host> 'systemctl --user status --no-pager mcp-as-a-service.service'
```

--------------------------------

### CoinGecko SSE Smoke Test

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Execute a smoke test for the CoinGecko SSE endpoint, capturing the first 8 Server-Sent Events. This verifies the real-time data stream connection.

```bash
ssh ubuntu@<host> 'timeout 10 curl -sS -N \
  "http://127.0.0.1:8787/package/%40coingecko%2Fcoingecko-mcp/sse?COINGECKO_ENVIRONMENT=demo&COINGECKO_DEMO_API_KEY=test" \
  | sed -n "1,8p"'
```

--------------------------------

### View Error Log File

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Tail the last 100 lines of the error log file for mcp-as-a-service. This is crucial for identifying and resolving specific errors.

```bash
ssh ubuntu@<host> 'tail -n 100 ~/mcp-as-a-service/error.log'
```

--------------------------------

### View MCP Service Logs

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Retrieve the latest 100 lines from the mcp-as-a-service journal logs. This is useful for diagnosing issues and understanding service behavior.

```bash
ssh ubuntu@<host> 'journalctl --user -u mcp-as-a-service.service -n 100 --no-pager'
```

--------------------------------

### DNS A Record Configuration

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Configure an 'A' record to point your MCP service domain to your origin server's IP address. Ensure the 'Proxy status' is set to 'Proxied' (Orange cloud) for Cloudflare's protection and performance benefits.

```text
Type: A
Name: mcp (or @ for root)
IPv4: YOUR_HETZNER_VPS_IP
Proxy status: Proxied (Orange cloud)
TTL: Auto
```

--------------------------------

### POST /package/:packageName/messages

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/API_REFERENCE.md

Sends a JSON-RPC payload to the runtime process of a specified package. Used for communication with the package's MCP server.

```APIDOC
## POST /package/:packageName/messages

### Description
Sends a JSON-RPC payload to the runtime process of a specified package. Used for communication with the package's MCP server.

### Method
POST

### Endpoint
/package/:packageName/messages

### Query Parameters
- **COINGECKO_ENVIRONMENT** (string) - Optional - Specifies the environment.
- **COINGECKO_DEMO_API_KEY** (string) - Optional - Demo API key for authentication.

### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (number) - Required - The ID of the request.
- **method** (string) - Required - The name of the method to call.
- **params** (object) - Optional - Parameters for the method call.

### Request Example
```bash
curl -X POST "http://127.0.0.1:8787/package/%40coingecko%2Fcoingecko-mcp/messages?COINGECKO_ENVIRONMENT=demo&COINGECKO_DEMO_API_KEY=test" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

### Response
#### Success Response (200)
- **accepted** (boolean) - Indicates if the message was accepted.

### Response Example
{
  "accepted": true
}

```

--------------------------------

### Rollback Service Deployment

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/DEPLOYMENT.md

Reverts the server repository to a known good commit or tag, reinstalls dependencies, restarts the service, and verifies the health endpoint. This is used if a deployment fails.

```bash
ssh ubuntu@<host> \
  'set -e
  cd ~/mcp-as-a-service
  git log --oneline -n 5
  git checkout <known-good-commit-or-tag>
  export PATH="$HOME/.bun/bin:$PATH"
  bun install
  systemctl --user restart mcp-as-a-service.service
  curl -sS http://127.0.0.1:8787/health
'
```

--------------------------------

### HTTP/SSE Proxy Endpoints

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/MCP_COMPLIANCE.md

Endpoints for proxying Server-Sent Events (SSE) and handling messages for specific packages.

```APIDOC
## GET /package/:packageName/sse

### Description
Establishes a Server-Sent Events (SSE) stream for a given package.

### Method
GET

### Endpoint
/package/:packageName/sse

### Parameters
#### Path Parameters
- **packageName** (string) - Required - The name of the package to stream events for.

## POST /package/:packageName/messages

### Description
Sends messages to a specific package.

### Method
POST

### Endpoint
/package/:packageName/messages

### Parameters
#### Path Parameters
- **packageName** (string) - Required - The name of the package to send messages to.
#### Request Body
- **message** (string) - Required - The message content to send.

### Request Example
```json
{
  "message": "Hello, package!"
}
```
```

--------------------------------

### Test Rate Limiting

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Execute a loop of POST requests to the '/package/firecrawl-mcp/messages' endpoint to test the rate limiting configuration. This script sends 25 requests with a 1-second delay between each.

```bash
# Test rate limiting
for i in {1..25}; do
  curl -w "%{http_code}\n" -o /dev/null -s \
    -X POST "https://mcp.llmbase.ai/package/firecrawl-mcp/messages?test=rate$i" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
  sleep 1
done
```

--------------------------------

### Cache Static Responses Rule

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Configure a caching rule to cache static API documentation responses for 5 minutes. This improves performance by serving cached content for requests to the root path.

```text
Rule Name: Cache API Documentation
Match: URI Path equals "/"
Cache Level: Standard
Edge TTL: 5 minutes
```

--------------------------------

### Check Service Health Endpoint

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Perform a basic health check by querying the /health endpoint of the mcp-as-a-service. This verifies if the service is operational.

```bash
ssh ubuntu@<host> 'curl -sS http://127.0.0.1:8787/health'
```

--------------------------------

### Stop MCP Service

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Gracefully stop the mcp-as-a-service. Use this command when maintenance is required or the service needs to be temporarily disabled.

```bash
ssh ubuntu@<host> 'systemctl --user stop mcp-as-a-service.service'
```

--------------------------------

### Active Runtime Stats

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Provides statistics on active runtimes.

```APIDOC
## GET /servers

### Description
Provides statistics on active runtimes.

### Method
GET

### Endpoint
/servers

```

--------------------------------

### Check User Lingering Setting

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Check if user lingering is enabled for the 'ubuntu' user. Lingering must be enabled for user services to persist after the user logs out.

```bash
ssh ubuntu@<host> 'loginctl show-user ubuntu -p Linger'
```

--------------------------------

### Send Package Message

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Sends JSON-RPC payloads to a specific package runtime. This is the canonical write endpoint.

```APIDOC
## POST /package/:packageName/messages

### Description
Sends JSON-RPC payloads to a specific package runtime. This is the canonical write endpoint.

### Method
POST

### Endpoint
/package/:packageName/messages

### Parameters
#### Path Parameters
- **packageName** (string) - Required - The name of the package.

#### Query Parameters
- **firecrawlApiKey** (string) - Required - API key for Firecrawl (if applicable).

#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (integer) - Required - The ID of the request.
- **method** (string) - Required - The method to be called.
- **params** (object) - Optional - Parameters for the method call.

### Request Example
```bash
curl -X POST "http://127.0.0.1:8787/package/firecrawl-mcp/messages?firecrawlApiKey=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The ID of the request.
- **result** (any) - The result of the method call.
- **error** (object) - An error object if the call failed.
  - **code** (integer) - The error code.
  - **message** (string) - The error message.

```

--------------------------------

### Package SSE Stream

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Streams server events and messages for a specific package.

```APIDOC
## GET /package/:packageName/sse

### Description
Streams server events and messages for a specific package.

### Method
GET

### Endpoint
/package/:packageName/sse

### Parameters
#### Query Parameters
- **firecrawlApiKey** (string) - Required - API key for Firecrawl (if applicable).

### Request Example
```bash
curl -N "http://127.0.0.1:8787/package/firecrawl-mcp/sse?firecrawlApiKey=YOUR_KEY"
```

```

--------------------------------

### MCP JSON-RPC Endpoints

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/MCP_COMPLIANCE.md

The service implements MCP over JSON-RPC 2.0. The primary endpoint for JSON-RPC communication is POST /mcp. Supported methods include initialize, notifications/initialized, capabilities/list, tools/list, resources/list, and prompts/list.

```APIDOC
## POST /mcp

### Description
Handles MCP protocol operations via JSON-RPC 2.0.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to call (e.g., `initialize`, `capabilities/list`).
- **params** (object) - Optional - Parameters for the method.
- **id** (string | number | null) - Required - The request ID.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05"
  },
  "id": "request-1"
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the method call.
- **id** (string | number | null) - The request ID.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "serverInfo": {
      "name": "mcp-as-a-service",
      "version": "1.0.0"
    },
    "capabilities": [
      "capabilities/list",
      "tools/list"
    ]
  },
  "id": "request-1"
}
```

### Error Handling
Standard JSON-RPC 2.0 error codes and MCP-specific error codes are returned in the `error` field of the response.
```

--------------------------------

### Custom Firewall Rule: Block Bad Patterns

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Implement a custom firewall rule using JavaScript to block common malicious patterns in URI queries, such as PHP, script tags, or JavaScript/VBScript calls. This enhances security against injection attacks.

```javascript
// Block common attack patterns
(http.request.uri.query contains "<?php" or 
 http.request.uri.query contains "<script" or
 http.request.uri.query contains "javascript:" or
 http.request.uri.query contains "vbscript:")
```

--------------------------------

### Enable User Lingering

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/DEPLOYMENT.md

Enables user lingering for reboot persistence. This ensures user services remain active after a reboot.

```bash
sudo loginctl enable-linger ubuntu
```

--------------------------------

### DNS CNAME Record for Subdomain

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Optionally, configure a 'CNAME' record for a subdomain like 'api' to point to your main MCP domain. This is useful for organizing services under different hostnames.

```text
Type: CNAME
Name: api
Target: mcp.llmbase.ai
Proxy status: Proxied
```

--------------------------------

### Page Rule to Bypass Package Caching

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Legacy Page Rule to bypass caching for package requests and enforce a high security level. Use the Rules engine for new configurations.

```text
2. mcp.llmbase.ai/package/*
   - Cache Level: Bypass
   - Security Level: High
```

--------------------------------

### Package Endpoint Rate Limiting Rule

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Implement a more restrictive rate limiting rule specifically for the '/package/' endpoint to protect sensitive package operations. This rule limits requests to 20 per minute per IP.

```text
Rule Name: MCP Package Endpoint Rate Limit  
Match: 
  - Hostname equals "mcp.llmbase.ai"
  - URI Path starts with "/package/"
Rate: 20 requests per minute per IP
Action: Block for 5 minutes
```

--------------------------------

### Verify Service Health

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/DEPLOYMENT.md

Checks the health status and server list of the mcp-as-a-service. Expected results include an active service, healthy status, and podman execution mode.

```bash
ssh ubuntu@<host> 'curl -sS http://127.0.0.1:8787/health'
```

```bash
ssh ubuntu@<host> 'curl -sS http://127.0.0.1:8787/servers'
```

--------------------------------

### Page Rule for General Caching

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Legacy Page Rule for general caching of all other requests, applying standard caching and medium security level. Use the Rules engine for new configurations.

```text
3. mcp.llmbase.ai/*
   - Cache Level: Standard
   - Edge Cache TTL: 5 minutes
   - Security Level: Medium
```

--------------------------------

### Basic API Rate Limiting Rule

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Configure a basic rate limiting rule for the MCP API to block excessive requests per IP per minute. This rule applies to all requests to the 'mcp.llmbase.ai' hostname.

```text
Rule Name: MCP API Rate Limit
Match: Hostname equals "mcp.llmbase.ai"
Rate: 100 requests per minute per IP
Action: Block for 10 minutes
```

--------------------------------

### API Removed Alias Test (Respond)

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Verify that accessing a removed alias endpoint like /respond for firecrawl-mcp returns a 404 Not Found status code. This checks API endpoint security and configuration.

```bash
ssh ubuntu@<host> 'curl -sS -o /dev/null -w "%{http_code}\n" -X POST \
  "http://127.0.0.1:8787/package/firecrawl-mcp/respond" -H "Content-Type: application/json" -d "{}"'
```

--------------------------------

### MCP Protocol Endpoint

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

The primary JSON-RPC 2.0 endpoint for MCP communication.

```APIDOC
## POST /mcp

### Description
The primary JSON-RPC 2.0 endpoint for MCP communication.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (integer) - Required - The ID of the request.
- **method** (string) - Required - The method to be called.
- **params** (object) - Optional - Parameters for the method call.
  - **protocolVersion** (string) - Required - The MCP protocol version.
  - **capabilities** (object) - Optional - Client capabilities.
  - **clientInfo** (object) - Optional - Information about the client.
    - **name** (string) - Required - The name of the client.
    - **version** (string) - Required - The version of the client.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test",
      "version": "1.0"
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The ID of the request.
- **result** (any) - The result of the method call.
- **error** (object) - An error object if the call failed.
  - **code** (integer) - The error code.
  - **message** (string) - The error message.

```

--------------------------------

### MCP Status Discovery Endpoint

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/MCP_COMPLIANCE.md

Provides MCP capabilities discovery via a dedicated HTTP endpoint.

```APIDOC
## GET /mcp/capabilities

### Description
Retrieves the MCP capabilities of the service.

### Method
GET

### Endpoint
/mcp/capabilities

### Response
#### Success Response (200)
- **capabilities** (array) - A list of supported MCP capabilities.

#### Response Example
```json
{
  "capabilities": [
    "capabilities/list",
    "tools/list",
    "resources/list",
    "prompts/list"
  ]
}
```
```

--------------------------------

### Cache Health Checks Rule

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Configure a rule to cache health check responses for 1 minute. This reduces the load on the origin server by serving cached health status for '/health' requests.

```text
Rule Name: Cache Health Checks
Match: URI Path equals "/health"
Cache Level: Standard
Edge TTL: 1 minute
```

--------------------------------

### API Removed Alias Test (Message)

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Verify that accessing a removed alias endpoint like /message for firecrawl-mcp returns a 404 Not Found status code. This confirms that only intended API paths are accessible.

```bash
ssh ubuntu@<host> 'curl -sS -o /dev/null -w "%{http_code}\n" -X POST \
  "http://127.0.0.1:8787/package/firecrawl-mcp/message" -H "Content-Type: application/json" -d "{}"'
```

--------------------------------

### Health Check Exception Rule

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Create an exception rule for health check requests to '/health' to ensure they bypass rate limiting and other security checks. This prevents monitoring systems from being blocked.

```text
Rule Name: Health Check Exception
Match:
  - Hostname equals "mcp.llmbase.ai" 
  - URI Path equals "/health"
Action: Skip all remaining rules
```

--------------------------------

### API Ping Endpoint Test

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/OPERATIONS.md

Test the canonical API endpoint for the firecrawl-mcp package by sending a POST request with a 'ping' method. This verifies basic API communication and returns the HTTP status code.

```bash
ssh ubuntu@<host> 'curl -sS -o /dev/null -w "%{http_code}\n" -X POST \
  "http://127.0.0.1:8787/package/firecrawl-mcp/messages" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}"'
```

--------------------------------

### Page Rule for Health Checks

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/docs/CLOUDFLARE_SETUP.md

Legacy Page Rule to cache health check responses for 1 minute and apply standard caching. Use the Rules engine for new configurations.

```text
1. mcp.llmbase.ai/health*
   - Cache Level: Standard
   - Edge Cache TTL: 1 minute
```

--------------------------------

### Health Check

Source: https://github.com/llmbaseai/mcp-hosting/blob/main/README.md

Checks the health of the service and its protocol status.

```APIDOC
## GET /health

### Description
Checks the health of the service and its protocol status.

### Method
GET

### Endpoint
/health

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.