From 381c96c093adc6d7a0535bbf5118757c72b76498 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Fri, 30 Jan 2026 09:41:48 +0100 Subject: [PATCH] fix: improve doc on vertexai and mcp (#247) * fix: improve doc on vertexai and mcp * fix --- .../src/app/api/graph/route.ts | 2 +- .../src/lib/hindsight-client.ts | 6 +-- .../docs/developer/configuration.md | 35 +++++++++++----- hindsight-docs/docs/developer/mcp-server.md | 41 +++++++++++++++++++ 4 files changed, 69 insertions(+), 15 deletions(-) diff --git a/hindsight-control-plane/src/app/api/graph/route.ts b/hindsight-control-plane/src/app/api/graph/route.ts index f93fb605..dead8337 100644 --- a/hindsight-control-plane/src/app/api/graph/route.ts +++ b/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 } ); } diff --git a/hindsight-control-plane/src/lib/hindsight-client.ts b/hindsight-control-plane/src/lib/hindsight-client.ts index 038865e4..e48a6912 100644 --- a/hindsight-control-plane/src/lib/hindsight-client.ts +++ b/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, + }) ); /** diff --git a/hindsight-docs/docs/developer/configuration.md b/hindsight-docs/docs/developer/configuration.md index d3749099..d94f3454 100644 --- a/hindsight-docs/docs/developer/configuration.md +++ b/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." diff --git a/hindsight-docs/docs/developer/mcp-server.md b/hindsight-docs/docs/developer/mcp-server.md index f57d7479..e512e2e3 100644 --- a/hindsight-docs/docs/developer/mcp-server.md +++ b/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.