Properties

category: reference
tags: [meta, design, prd, mcp]
last_updated: 2026-03-12
confidence: high

Original PRD MCP

This page is part of the original single-tenant PRD, split across five wiki pages: Design/Research Wiki | Design/Rest Api | Design/Semantic Search | Design/Mcp Server | Design/Note_Schema

Component 3: MCP Server

Goal

Expose the wiki API as MCP tools over SSE so that Claude.ai can read, write, search, and navigate the wiki during conversations.

Implementation

A standalone Python service using FastMCP that translates MCP tool calls into HTTP requests to the Otterwiki REST API.

Tools

Tool Name	Description	Maps to API
`read_note`	Read a wiki page by path. Returns frontmatter + content + links.	`GET /api/v1/pages/<path>`
`write_note`	Create or update a wiki page. Accepts path, content, commit message.	`PUT /api/v1/pages/<path>`
`list_notes`	List pages. Optional filters: `prefix`, `category`, `tag`, `updated_since`. Filters compose with AND.	`GET /api/v1/pages?...`
`search_notes`	Full-text keyword search.	`GET /api/v1/search?q=...`
`semantic_search`	Semantic similarity search via Chroma.	`GET /api/v1/semantic-search?q=...&n=...`
`get_links`	Get incoming and outgoing WikiLinks for a page.	`GET /api/v1/links/<path>`
`get_recent_changes`	Get recent changelog entries.	`GET /api/v1/changelog?limit=...`
`delete_note`	Delete a wiki page.	`DELETE /api/v1/pages/<path>`
`find_orphaned_notes`	List pages not referenced in any index page. Used during gardening sessions to catch notes that fell through the cracks.	`GET /api/v1/pages` minus pages linked from any page with `category: index`. Implemented in the MCP server, not the API — it calls `list_notes` and `read_note` on index pages, then diffs.

Configuration

Environment variables:

OTTERWIKI_API_URL — internal URL of Otterwiki (e.g., http://otterwiki:80)
OTTERWIKI_API_KEY — API key for authentication
MCP_PORT — port for SSE endpoint (default: 8090)

Tool return format and error handling

MCP tools return plain text (not JSON) to Claude.ai, since the AI assistant is the consumer and reads text more efficiently than structured data. The MCP server is responsible for translating API JSON responses into readable text.

Successful read_note return:

# Iran Attrition Strategy
Path: Trends/Iran Attrition Strategy
Category: trend | Tags: military, p2-interceptor-race, p3-infrastructure
Confidence: high | Last updated: 2026-03-08
Links to: Variables/Interceptor Stockpiles, Propositions/Iran Rationing Ballistic Missiles, Actors/Iran, Trends/Desalination Targeting Ratchet
Linked from: Actors/Iran, Propositions/Iran Rationing Ballistic Missiles

---
[full markdown content here, including frontmatter]

Successful list_notes return (with category=proposition):

Found 2 notes matching category=proposition:

- Propositions/Iran Rationing Ballistic Missiles (proposition, 487 words, updated 2026-03-08)
- Propositions/Fertilizer Supply Chain Disruption (proposition, 312 words, updated 2026-03-07)

Successful list_notes return (with tag=p2-interceptor-race):

Found 4 notes matching tag=p2-interceptor-race:

- Trends/Iran Attrition Strategy (trend, 487 words, updated 2026-03-08)
- Variables/Interceptor Stockpiles (variable, 342 words, updated 2026-03-08)
- Propositions/Iran Rationing Ballistic Missiles (proposition, 487 words, updated 2026-03-08)
- Actors/Gulf States (actor, 523 words, updated 2026-03-07)

Successful list_notes return (with updated_since=2026-03-08):

Found 5 notes updated since 2026-03-08:

- Events/2026-03-08 New Iranian Supreme Leader Selected (event, 189 words, updated 2026-03-08)
- Events/2026-03-08 Russia Providing Targeting Intelligence (event, 234 words, updated 2026-03-08)
- Trends/Iran Attrition Strategy (trend, 487 words, updated 2026-03-08)
- Variables/WTI Oil Price (variable, 156 words, updated 2026-03-08)
- Variables/Interceptor Stockpiles (variable, 342 words, updated 2026-03-08)

Successful semantic_search return:

3 results for "strategy for depleting Gulf air defenses":

1. Trends/Iran Attrition Strategy (distance: 0.34)
   Iran is executing a multi-phase attrition campaign designed to degrade Gulf state and US defensive capacity...

2. Variables/Interceptor Stockpiles (distance: 0.41)
   Tracking estimated remaining interceptor inventories across Gulf state Patriot and THAAD batteries...

3. Propositions/Iran Rationing Ballistic Missiles (distance: 0.48)
   The 86% drop in ballistic missile launch rates reflects deliberate rationing, not destroyed capability...

Error handling:

Tools should return clear, actionable error messages — never raw exceptions or stack traces. The MCP server catches HTTP errors from the API and translates them:

API status	MCP tool returns
404	`Page not found: Actors/Iran. Use write_note to create it, or list_notes to see available pages.`
401	`Authentication failed. The API key may be misconfigured.`
409	`Conflict: the page was modified since last read. Read the page again to get the current version, then retry.`
422	`Invalid request: [detail from API error message]`
500 / timeout	`The wiki API is not responding. It may be restarting. Try again in a few seconds.`

The guiding principle: errors should help Claude (the AI) take a useful next action, not just report what went wrong.

SSE endpoint

The MCP server exposes an SSE endpoint at https://<host>/mcp (behind reverse proxy with TLS). This URL is added to Claude.ai's MCP server connections.