Corpus API and MCP

WriterzRoom has two deliberately different corpus access paths:

Path	Scope	Intended caller
Authenticated Corpus API	Shared curated chunks plus only the authenticated user’s private documents	WriterzRoom users and their server-side integrations
Curated Corpus MCP	Shared curated chunks only; read-only and never includes private uploads	Approved agents and services with Cloud Run IAM access

Retrieval covers all ten vertical IDs: education, enterprise_operations, entertainment, fintech, healthcare, healthcare_legal, legal, political, real_estate, and saas_tech.

Retrieval relevance is not proof of factual correctness. Check source authority, publication date, context, and the underlying document before relying on a result.

Private Corpus API

All routes below use https://api.writerzroom.com/api and a user API key. Ownership is resolved from that credential; clients cannot supply or override an owner ID.

Upload a document

curl -X POST https://api.writerzroom.com/api/corpus/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "enterprise_operations",
    "source_title": "Approved operating model",
    "source_url": "https://intranet.example/operating-model",
    "text": "The full reference text, at least 100 characters..."
  }'

The response returns a content-derived document_id, the stored chunk count, and scope: private. Text is capped at 500,000 characters per request.

List, inspect, search, and delete

Method	Endpoint	Purpose
`GET`	`/corpus/documents`	List the caller’s private documents
`GET`	`/corpus/documents/stats`	Count the caller’s private documents and chunks
`POST`	`/corpus/search`	Search curated material plus the caller’s private documents; `top_k` is 1–50
`DELETE`	`/corpus/documents/{document_id}`	Delete only the caller’s matching private chunks

{
  "query": "What approval sequence does the operating model require?",
  "vertical": "enterprise_operations",
  "top_k": 10
}

The product’s private-corpus controls provide the same upload, list, search, statistics, and delete operations. Shared ingestion routes (/corpus/ingest, /corpus/ingest/document, /corpus/stats, and /corpus/vertical/{vertical}) are administrator-only and should not be exposed to end users.

Curated Corpus MCP

The MCP process exposes three tools:

Tool	Behavior
`search_curated_corpus`	Hybrid dense and lexical search with reciprocal-rank fusion; `top_k` is capped at 20
`list_curated_corpus`	Supported verticals and aggregate curated coverage; excludes private counts
`corpus_capabilities`	Read-only boundary, retrieval methods, vertical IDs, and explicit non-claims

The MCP calls corpus search without a user ID. The store then admits only rows whose owner is null. This is the enforced tenant boundary, not a client option.

The service code and deployment configuration are included in the repository, but this documentation does not assert that your environment has deployed it. The following steps are required before first use.

Operator Deployment

The deployment uses Dockerfile.corpus-mcp and cloudbuild.corpus-mcp.yaml. It runs separately from the secret-free verification MCP because corpus retrieval needs database and Voyage embedding credentials.

Create the dedicated runtime identity

Create writerzroom-corpus-mcp@agentic-writer.iam.gserviceaccount.com. Do not reuse the main application runtime identity.

Grant least-privilege secret access

Grant that identity Secret Manager accessor on only database-url and voyage-api-key. Grant Cloud SQL connectivity only as required by the production database path. Do not grant project-wide Secret Manager access.

Verify private networking

Confirm the writerzroom-connector Serverless VPC Access connector exists in us-central1 and can reach the database. The deployment sends only private ranges through it.

Build and deploy

From the repository root, run gcloud builds submit --config cloudbuild.corpus-mcp.yaml --project agentic-writer. The configuration keeps the service private with --no-allow-unauthenticated.

Authorize callers explicitly

Grant roles/run.invoker on writerzroom-corpus-mcp only to the service accounts that should call it. MCP clients must send a Google-signed identity token whose audience is the deployed Cloud Run service URL.

Smoke-test the boundary

Call corpus_capabilities, then list_curated_corpus, then a scoped search. Confirm curated_only: true, includes_private_documents: false, all ten verticals, and no private document titles or counts.

Required Owner Actions

Confirm the dedicated service account exists and its IAM bindings are no broader than documented.
Confirm database-url and voyage-api-key contain production-ready values and that the existing 1,536-dimension corpus index remains compatible with voyage-large-2.
Confirm the VPC connector and database route from Cloud Run.
Choose and authorize each MCP caller identity; the service must remain private.
Deploy and perform the curated-only boundary smoke test before advertising the MCP as available.

Source Quality

Understand scoring, citations, and the limits of retrieval.

API Authentication

Create and protect user API keys for private corpus access.

API

Architecture

Reference

Roadmap

Private Corpus API

Upload a document

List, inspect, search, and delete

Curated Corpus MCP

Operator Deployment

Required Owner Actions

Source Quality

API Authentication

​Private Corpus API

​Upload a document

​List, inspect, search, and delete

​Curated Corpus MCP

​Operator Deployment

​Required Owner Actions

Source Quality

API Authentication

Private Corpus API

Upload a document

List, inspect, search, and delete

Curated Corpus MCP

Operator Deployment

Required Owner Actions