Corpus API and MCP - WriterzRoom

WriterzRoom has two deliberately different corpus access paths:

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

Every document is in exactly one scope: curated (shared), private (one account), or organization (every active member of a workspace). Search results and document listings report the scope, a locator (corpus://<vertical>/<document_id>) that identifies the document when it has no URL, and provenance naming how it was ingested — including the connector and origin record for synced documents. Those same fields reach the writer’s reference list and the asset dossier, so content grounded in your material is cited to it. 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.

Workspace Documents

Members of a Professional or Enterprise workspace share a second corpus scope. The workspace is resolved from the caller’s membership; it is never supplied in the request.

Method	Endpoint	Who	Purpose
`GET`	`/corpus/organization/documents`	Any active member	List the workspace’s documents, with scope, locator, and provenance
`GET`	`/corpus/organization/documents/stats`	Any active member	Count workspace documents and chunks
`POST`	`/corpus/organization/documents`	Workspace owner or admin	Index a document every member’s generations may retrieve
`DELETE`	`/corpus/organization/documents/{document_id}`	Workspace owner or admin	Remove a workspace document’s chunks

The request body for POST is the same as for a private upload. Workspace documents belong to the workspace: removing the member who added one does not remove it, and the uploader is recorded for the audit trail. POST /corpus/search searches curated material, the caller’s private documents, and their workspace’s documents together.

Connectors

A connector indexes documents from a system you own on each sync, and can be queried live while content is generated. Connectors are personal or workspace-scoped, bound to one vertical, and their credential is encrypted at rest and never returned.

Method	Endpoint	Purpose
`GET`	`/corpus/connectors/types`	Available connector types with their settings schema
`GET`	`/corpus/connectors`	The caller’s connectors and their workspace’s, with `can_manage` per connector
`POST`	`/corpus/connectors`	Create a connector; settings are validated before anything is stored
`POST`	`/corpus/connectors/{id}/sync`	Run a sync now; `{"full": true}` ignores the last sync time
`PATCH`	`/corpus/connectors/{id}/status?status=disabled`	Disable or re-enable a connector
`DELETE`	`/corpus/connectors/{id}`	Remove a connector; documents it synced stay in the corpus

{
  "name": "Support tickets",
  "type": "sql_table",
  "vertical": "saas_tech",
  "mode": "both",
  "scope": "organization",
  "settings": {
    "table": "support.tickets",
    "id_column": "id",
    "text_columns": ["subject", "body"],
    "title_column": "subject",
    "updated_at_column": "updated_at",
    "limit": 500
  },
  "credential": "postgresql://reader:password@warehouse.example.com:5432/support"
}

Type	Modes	Reads
`http_documents`	`sync`	Up to 50 fixed HTTP(S) URLs, optionally behind a bearer token
`sql_table`	`sync`, `live`, `both`	One PostgreSQL table or view, read-only; live mode runs a full-text query over the configured columns when content is generated

Workspace-scoped connectors require the workspace owner or admin role. Table and column names must be plain identifiers; there is no free-form query setting. Connectors cannot target loopback, link-local, or cloud-metadata addresses, and private network ranges are refused unless the operator has enabled them for a deployment whose egress reaches the customer network. Documents that arrive through a connector carry provenance — the connector id, its type, the origin record’s id, and the sync time — on every search result and in the asset dossier of any content that cites them.

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 or a workspace ID. The store then admits only rows in the curated scope — neither an owner nor a workspace set. 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.

​Private Corpus API

​Upload a document

​List, inspect, search, and delete

​Workspace Documents

​Connectors

​Curated Corpus MCP

​Operator Deployment

​Required Owner Actions

Source Quality

API Authentication

Private Corpus API

Upload a document

List, inspect, search, and delete

Workspace Documents

Connectors

Curated Corpus MCP

Operator Deployment

Required Owner Actions