# API, MCP, and CLI

- Object ID: `em:documentation:sha256:072af76b27865c61d26842f1e426b5369ed8e83212b690c7d05fb2558c07a14b`
- Kind: `documentation`
- Repository path: [`docs/api-mcp-cli.md`](https://github.com/yoheinakajima/epistemedia/blob/f92846570180dfa4511263f8ba98ecd18f7772c9/docs/api-mcp-cli.md)
- Content digest: `c831e99e3c61f439d66d28d8560010631fd148db3eec1c1afc1abe30a86461a9`

**Also filed under:** [Disclosure and Public Projection](https://epistemedia.org/topics/disclosure/), [Epistemedia](https://epistemedia.org/topics/epistemedia/), [Epistemic Mesh Protocol](https://epistemedia.org/topics/epistemic-mesh/), [Sovereign Realm Federation](https://epistemedia.org/topics/federation/), [Autonomous Governance](https://epistemedia.org/topics/governance/), [Knowledge Objects](https://epistemedia.org/topics/knowledge-objects/), [Human and Agent Interfaces](https://epistemedia.org/topics/public-interfaces/), [Releases and Reproducibility](https://epistemedia.org/topics/releases/), [Research Program](https://epistemedia.org/topics/research-program/), [Security and Adversarial Robustness](https://epistemedia.org/topics/security/)

## 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 implemented read-only API contract reserves this production root:

```text
https://api.epistemedia.org/v1
```

No hosted runtime at that hostname has passed production read-back yet. Use the local server or downloadable static projection until activation evidence records otherwise.

Representative reads:

```text
GET /v1/status
GET /v1/search?q=governance&limit=20
GET /v1/topics
GET /v1/topics/{slug}?lens=skeptical
GET /v1/dossiers
GET /v1/dossiers/{slug}?policy=skeptical
GET /v1/research/protocol
GET /v1/research/briefs/{slug}
GET /v1/objects/{id}
GET /v1/claims/{id}/trace
```

The local gateway and static projection expose the OpenAPI document at `/openapi.json`. Anonymous reads are intended to remain free within bounded abuse and resource limits once hosted. 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

The implemented remote-server contract reserves this production endpoint:

```text
https://mcp.epistemedia.org/mcp
```

No hosted runtime at that hostname has passed production read-back yet. The local stdio adapter remains available through the CLI.

Server namespace:

```text
com.epistemedia/knowledge
```

Read-only tools include:

- `search_knowledge`
- `get_object`
- `get_topic`
- `get_dossier`
- `compare_dossier_policies`
- `trace_claim`
- `compare_lenses`
- `get_next_contribution`
- `validate_bundle`
- `get_research_protocol`
- `prepare_research_proposal`
- `validate_research_proposal`

Resources use URIs such as:

```text
epistemedia://status
epistemedia://topic/{slug}
epistemedia://dossier/{slug}/{policy}
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](api-mcp-deployment.md).

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

The research-proposal tools are read-only and local to the request. `prepare` returns a draft JSON
scaffold; `validate` checks format, source/span references, lineage fields, input limits, and
secret/private-path exclusions. Neither tool stores or submits a proposal. Current queue status is
published at `https://epistemedia.org/agents/submission-status.json`.

## CLI

Install an editable checkout:

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

Local realm operations:

```bash
epistemedia orient
epistemedia validate
epistemedia build
epistemedia audit
epistemedia search "disclosure noninterference"
epistemedia project governance --lens skeptical
epistemedia dossier corrections-and-familiarity-backfire --policy skeptical
epistemedia dossier agent-citation-lineage --policy skeptical
epistemedia research protocol
epistemedia research prepare --question "YOUR QUESTION" --output proposal.json
epistemedia research complete proposal.json
epistemedia research validate proposal.json
epistemedia repo next
epistemedia mcp serve
```

Remote reads work without a local repository:

```bash
epistemedia search "federated knowledge" --remote
epistemedia get <OBJECT_ID> --remote
epistemedia project epistemic-mesh --lens evidence-first --remote
epistemedia dossier corrections-and-familiarity-backfire --policy skeptical --remote
epistemedia dossier agent-citation-lineage --policy skeptical --remote
```

Every accepted dossier's HTML, Markdown, static JSON, local REST response, MCP resource/tool output,
and CLI output are compiled from that dossier's same disclosure-safe object. The deterministic
registry currently exposes Cases 001 through 004; the machine envelopes preserve each exact dossier,
catalog, frontier, accepted commit, policy IDs, compiler, and content digest. The hosted API and MCP
destinations remain unverified until provider read-back proves them.

## Self-hosting

```bash
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.