# ServerMCP - how to connect

ServerMCP exposes read tools plus policy-gated write tools (`run_action`, `set_env`) over the Model Context Protocol (MCP). Read tools are scoped by the credential grant; every call is policy-checked and audited, secrets are redacted and `.env` values are masked.

## Connect

- Streamable HTTP endpoint: `POST /mcp`
- Authenticate with `Authorization: Bearer <token>`, or use the connect URL `POST /mcp/{token}`.

## Tools

- `list_servers` - List the servers this credential is allowed to see.
- `get_server` - Return inventory and status for one server.
- `read_file` - Read a text file inside a site, relative to the site root.
- `list_dir` - List a directory inside a site, relative to the site root.
- `tail_log` - Tail a site log (laravel, nginx or php_fpm).
- `search_logs` - Search a site log (laravel, nginx or php_fpm) for a pattern.
- `mysql_query` - Run one read-only SELECT/WITH query against a site database.
- `get_env` - Return the site .env with every value masked.
- `get_metrics` - Return a resource-usage snapshot (cpu, memory, disk, network, load) for one server.
- `get_nginx_config` - Return the server nginx configuration (nginx -T), scrubbed of site secrets.
- `run_action` - Run one allow-listed action on a server or site (restart:nginx, reload:php-fpm, cache:clear, config:cache, config:clear, artisan:optimize, queue:restart, update:node, rollback:node). Policy-gated; some actions require approval. update:node takes a [version] and installs that signed release on the server; rollback:node takes a [version] and re-activates that previously installed version.
- `set_env` - Set one key in a site .env file. Always requires human approval by default; the value is never returned or logged.
- `get_approval_status` - Return the status and result of an approval previously requested by this credential.

## Approvals

Actions are deny-by-default and may require human approval. A gated call returns immediately with:

```json
{"status":"pending_approval","approval_id":123,"message":"...","approve_url":"..."}
```

Relay the `message` to the user, then poll `get_approval_status` with the `approval_id` until it reports a decided status (`executed`, `denied`, `failed` or `expired`).

## Scoped instructions

Fetch `GET /agents/{token}` with your credential to see the servers and tools your grant allows.

## Safety

- Access is fail-closed: an invalid, revoked or expired credential gets a 401.
- Every call is policy-checked and audited; secrets are redacted and `.env` values are masked.
- `run_action` only runs a fixed allowlist of actions; `set_env` writes one `.env` key and is always masked.