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/Original PRD Semantic Search | Design/Original PRD MCP | Design/Original PRD 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 authenticationMCP_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.