fix: improve doc on vertexai and mcp (#247)

* fix: improve doc on vertexai and mcp

* fix

hindsight-control-plane/src/app/api/graph/route.ts

@@ -28,7 +28,7 @@ export async function GET(request: NextRequest) {
       console.error("Graph API error:", response.error);
       return NextResponse.json(
         { error: response.error || "Failed to fetch graph data" },
-        { status: 500 },
+        { status: 500 }
       );
     }
 

hindsight-control-plane/src/lib/hindsight-client.ts

@@ -33,10 +33,8 @@ export const hindsightClient = new HindsightClient({
 export const lowLevelClient = createClient(
   createConfig({
     baseUrl: DATAPLANE_URL,
-    headers: DATAPLANE_API_KEY
-      ? { Authorization: `Bearer ${DATAPLANE_API_KEY}` }
-      : undefined,
-  }),
+    headers: DATAPLANE_API_KEY ? { Authorization: `Bearer ${DATAPLANE_API_KEY}` } : undefined,
+  })
 );
 
 /**

hindsight-docs/docs/developer/configuration.md

@@ -97,9 +97,9 @@ export HINDSIGHT_API_LLM_PROVIDER=anthropic
 export HINDSIGHT_API_LLM_API_KEY=sk-ant-xxxxxxxxxxxx
 export HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-20250514
 
-# Vertex AI (Google Cloud)
+# Vertex AI (Google Cloud - uses native genai SDK)
 export HINDSIGHT_API_LLM_PROVIDER=vertexai
-export HINDSIGHT_API_LLM_MODEL=google/gemini-2.0-flash-001
+export HINDSIGHT_API_LLM_MODEL=gemini-2.0-flash-001
 export HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=your-gcp-project-id
 export HINDSIGHT_API_LLM_VERTEXAI_REGION=us-central1
 # Optional: use ADC (gcloud auth application-default login) or provide service account key:
@@ -124,7 +124,7 @@ export HINDSIGHT_API_LLM_MODEL=your-model-name
 
 #### Vertex AI Setup
 
-Google Cloud's Vertex AI provides OpenAI-compatible endpoints for Gemini models. Hindsight supports two authentication methods:
+Google Cloud's Vertex AI provides access to Gemini models via the native Google GenAI SDK. Hindsight supports two authentication methods:
 
 **Prerequisites:**
 - GCP project with Vertex AI API enabled
@@ -147,7 +147,7 @@ Google Cloud's Vertex AI provides OpenAI-compatible endpoints for Gemini models.
 
    # Configure Hindsight
    export HINDSIGHT_API_LLM_PROVIDER=vertexai
-   export HINDSIGHT_API_LLM_MODEL=google/gemini-2.0-flash-001
+   export HINDSIGHT_API_LLM_MODEL=gemini-2.0-flash-001
    export HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=your-project-id
    ```
 
@@ -163,14 +163,15 @@ Google Cloud's Vertex AI provides OpenAI-compatible endpoints for Gemini models.
 
    # Configure Hindsight
    export HINDSIGHT_API_LLM_PROVIDER=vertexai
-   export HINDSIGHT_API_LLM_MODEL=google/gemini-2.0-flash-001
+   export HINDSIGHT_API_LLM_MODEL=gemini-2.0-flash-001
    export HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=your-project-id
    export HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/path/to/key.json
    ```
 
-**Authentication Priority:** Hindsight tries ADC first, then falls back to service account key file if configured.
-
-**Token Management:** Access tokens expire after 60 minutes. Hindsight automatically refreshes tokens every 50 minutes in the background.
+**Notes:**
+- Model names can optionally include the `google/` prefix (e.g., `google/gemini-2.0-flash-001`) - it will be stripped automatically
+- The native SDK handles token refresh automatically
+- Uses service account credentials if provided, otherwise falls back to ADC
 
 ### Per-Operation LLM Configuration
 
@@ -481,15 +482,29 @@ Observations are consolidated knowledge synthesized from facts.
 |----------|-------------|---------|
 | `HINDSIGHT_API_REFLECT_MAX_ITERATIONS` | Max tool call iterations before forcing a response | `10` |
 
-### Local MCP Server
+### MCP Server
 
-Configuration for the local MCP server (`hindsight-local-mcp` command).
+Configuration for MCP server endpoints.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
+| `HINDSIGHT_API_MCP_ENABLED` | Enable MCP server at `/mcp/{bank_id}/` | `true` |
+| `HINDSIGHT_API_MCP_AUTH_TOKEN` | Bearer token for MCP authentication (optional) | - |
 | `HINDSIGHT_API_MCP_LOCAL_BANK_ID` | Memory bank ID for local MCP | `mcp` |
 | `HINDSIGHT_API_MCP_INSTRUCTIONS` | Additional instructions appended to retain/recall tool descriptions | - |
 
+**MCP Authentication:**
+
+By default, the MCP endpoint is open. For production deployments, set `HINDSIGHT_API_MCP_AUTH_TOKEN` to require Bearer token authentication:
+
+```bash
+export HINDSIGHT_API_MCP_AUTH_TOKEN=your-secret-token
+```
+
+Clients must then include the token in the `Authorization` header. See [MCP Server documentation](./mcp-server.md#authentication) for details.
+
+**Local MCP instructions:**
+
 ```bash
 # Example: instruct MCP to also store assistant actions
 export HINDSIGHT_API_MCP_INSTRUCTIONS="Also store every action you take, including tool calls and decisions made."

hindsight-docs/docs/developer/mcp-server.md

@@ -25,6 +25,47 @@ To disable the MCP server, set the environment variable:
 export HINDSIGHT_API_MCP_ENABLED=false
 ```
 
+## Authentication
+
+By default, the MCP endpoint is **open** for local development. For production deployments, enable authentication with a Bearer token:
+
+```bash
+export HINDSIGHT_API_MCP_AUTH_TOKEN=your-secret-token
+```
+
+When authentication is enabled, all MCP requests must include a valid `Authorization` header:
+
+**Claude Desktop config** (`.claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "hindsight": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-http-client", "http://localhost:8888/mcp/alice/"],
+      "env": {
+        "HTTP_HEADERS": "{\"Authorization\": \"Bearer your-secret-token\"}"
+      }
+    }
+  }
+}
+```
+
+**Claude Code config:**
+```bash
+claude mcp add --transport http hindsight http://localhost:8888/mcp/alice/ \
+  --header "Authorization: Bearer your-secret-token"
+```
+
+**Direct HTTP request:**
+```bash
+curl -X POST http://localhost:8888/mcp/alice/ \
+  -H "Authorization: Bearer your-secret-token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
+```
+
+If the token is missing or invalid, requests will receive a `401 Unauthorized` response.
+
 ## Per-Bank Endpoints
 
 Unlike traditional MCP servers where tools require explicit identifiers, Hindsight uses **per-bank endpoints**. The `bank_id` is part of the URL path, so tools don't need to specify which bank to use—it's implicit from the connection.