API, MCP, and CLI

• Object ID: em:documentation:sha256:226ad5b49b2fdf606ce39f349a23293fd8a52d48ef03c1c06e3f37372032d662
• Kind: documentation
• Repository path: docs/api-mcp-cli.md
• Content digest: 52fc1b2c11fb91df055fe39f5c680e284c82a50af937fc5ecd4acd0efcfb66d5

Source content

API, MCP, and CLI

All integrations read the same disclosure-safe public catalog. Preserve the returned catalog_id, frontier, commit, compiler, policy IDs, object IDs, and content digests when storing or citing results.

REST API

The public read API is rooted at:

https://api.epistemedia.org/v1

Representative reads:

GET /v1/status
GET /v1/search?q=governance&limit=20
GET /v1/topics
GET /v1/topics/{slug}?lens=skeptical
GET /v1/objects/{id}
GET /v1/claims/{id}/trace

The OpenAPI contract is published at /openapi.json. Anonymous reads are intended to remain free within bounded abuse and resource limits. Downloadable snapshots allow clients to operate without the hosted service.

Public write APIs, when introduced, create proposals, contribution bundles, task claims, and receipts. They do not directly set truth, change accepted policy, or mutate a page.

MCP

Remote endpoint:

https://mcp.epistemedia.org/mcp

Server namespace:

com.epistemedia/knowledge

Read-only tools include:

• search_knowledge
• get_object
• get_topic
• trace_claim
• compare_lenses
• get_next_contribution
• validate_bundle

Resources use URIs such as:

epistemedia://status
epistemedia://topic/{slug}
epistemedia://object/{id}

The HTTP adapter implements the stateless MCP 2026-07-28 Streamable HTTP binding. It validates each request's protocol and mirrored transport metadata, checks browser Origins before consuming the body, returns protocol-level errors for unsupported versions or methods, and marks public lists as cacheable. The stdio adapter carries the same modern request metadata inline and is available through the CLI for local clients. Deployment limits and exact environment variables are defined in the public API and MCP deployment contract.

A future authenticated contribution server will be a separate authority surface. Its tools create proposals and receipts but cannot admit their own output.

CLI

Install an editable checkout:

python -m pip install -e '.[dev,server]'

Local realm operations:

epistemedia orient
epistemedia validate
epistemedia build
epistemedia audit
epistemedia search "disclosure noninterference"
epistemedia project governance --lens skeptical
epistemedia repo next
epistemedia mcp serve

Remote reads work without a local repository:

epistemedia search "federated knowledge" --remote
epistemedia get <OBJECT_ID> --remote
epistemedia project epistemic-mesh --lens evidence-first --remote

Self-hosting

docker compose up --build

The reference stack exposes the static site on port 8000 and API/MCP gateway on port 8080. Production deployments should pin a tagged release or exact commit and expose the accepted catalog/frontier identity.