diff --git a/README.md b/README.md
index 15e9499..00c2464 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 The **PDF Analyzer MCP Server** gives AI agents the ability to read and
 analyze PDF documents, enabling document Q&A through natural conversations.
 
-Supports multiple LLM providers: **Google Gemini**, **Anthropic Claude**, and **OpenAI**. Choose your preferred provider and model during setup.
+Supports multiple LLM providers: **Google Gemini**, **Anthropic Claude**, and **OpenAI** on their direct APIs, plus **Google Vertex AI** and **Anthropic on Vertex AI** for service-account auth. Choose your preferred provider and model during setup.
 
 ## Native Install (Recommended)
 
@@ -73,9 +73,11 @@ You'll be prompted to choose from:
 | Provider | Fast Model | Flagship Model | Get API Key |
 |----------|-----------|----------------|-------------|
 | Google Gemini | Gemini 3 Flash | Gemini 3.1 Pro | [Google AI Studio](https://aistudio.google.com/apikey) |
-| Anthropic Claude | Claude Sonnet 4.6 | Claude Opus 4.6 | [Anthropic Console](https://console.anthropic.com/settings/keys) |
+| Anthropic Claude | Claude Sonnet 4.6 | Claude Opus 4.7 | [Anthropic Console](https://console.anthropic.com/settings/keys) |
 | OpenAI GPT | GPT-5.4 Mini | GPT-5.4 | [OpenAI Platform](https://platform.openai.com/api-keys) |
 
+Claude Opus 4.6 is offered alongside 4.7 as the previous flagship. The Vertex AI providers offer the same Gemini and Claude models, and authenticate with a service account JSON key file instead of an API key.
+
 You can re-run `--setup` at any time to switch providers or models.
 
 ## Connect the MCP with your favorite AI tool
@@ -119,8 +121,16 @@ The server accepts:
 | Linux (ARM64) | `pdf-analyzer-linux-arm64` |
 | Windows (x64) | `pdf-analyzer-windows-x64.exe` |
 
+## Running as a hosted server
+
+Setting `PORT` starts the server over Streamable HTTP instead of stdio, serving MCP at `/mcp`, a direct `POST /analyze` REST endpoint, and `GET /health`.
+
+See [deploy/README.md](deploy/README.md) for deploying it to Cloud Run, including the provider and auth matrix, the IAM roles each provider needs, and how to reach the private service.
+
 ## Documentation
 
+See [docs/architecture.md](docs/architecture.md) for how the server is put together.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
 
 ---
diff --git a/docs/architecture.md b/docs/architecture.md
index 69f2f30..b7670ea 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -10,8 +10,8 @@ Both modes expose the same `analyze_pdf` tool. The difference is how the client
 ┌─────────────┐    stdin/stdout    ┌────────────────┐     API call     ┌─────────────┐
 │  MCP Client  │ ◄──────────────► │  pdf-analyzer   │ ──────────────► │  LLM Provider │
 │  (e.g. Claude│                   │  (child process)│                  │  (Gemini, etc)│
-│   Code, VS   │                   │                 │                  │               │
-│   Code, etc) │                   │  reads local    │                  └───────────────┘
+│   Code,      │                   │                 │                  │               │
+│   Codex)     │                   │  reads local    │                  └───────────────┘
 └──────────────┘                   │  files directly │
                                    └─────────────────┘
 ```
@@ -23,7 +23,7 @@ The MCP client spawns `pdf-analyzer` as a child process. Communication happens o
 1. The client starts `pdf-analyzer` as a subprocess
 2. Client sends a JSON-RPC request over stdin (e.g., `tools/call` with `analyze_pdf`)
 3. The server reads the PDF from disk or fetches it from a URL
-4. The server sends the PDF to the configured LLM provider (Google Gemini, Anthropic Claude, or OpenAI) using the provider's API key stored in the OS credential store
+4. The server sends the PDF to the configured LLM provider (Google Gemini, Anthropic Claude, or OpenAI) using the provider's API key stored in the OS credential store. The Vertex AI providers authenticate with a service account JSON key file instead
 5. The server writes the JSON-RPC response to stdout
 
 **PDF sources supported:**
diff --git a/src/cli/commands.ts b/src/cli/commands.ts
index 3d5e188..89e4d3a 100644
--- a/src/cli/commands.ts
+++ b/src/cli/commands.ts
@@ -41,7 +41,8 @@ export const printHelp = (): void => {
 ${BINARY_NAME} v${VERSION}
 
 MCP server for analyzing PDF documents using AI.
-Supports Google Gemini, Google Vertex AI, Anthropic Claude, and OpenAI.
+Supports Google Gemini, Anthropic Claude, and OpenAI, plus Google Vertex AI
+and Anthropic on Vertex AI.
 
 USAGE:
   ${BINARY_NAME} [OPTIONS]