npm package: @myth-os/mcp
Description: MCP server for narrative identity, governance, eval quality, and memory. Gives your AI agent a persistent understanding of who it's working for.
Latest version: 0.2.1

# @myth-os/mcp

MCP server that gives AI agents persistent identity context, governance boundaries, quality eval, and cross-session memory. Connects to a [mythOS](https://github.com/starhub-studios/mythos) backend via HTTP.

Your agent forgets who it's working for every session. This fixes that.

## What it solves

- **Identity amnesia** -- Agents start every session blank. `mythos_getContext` loads the creator's voice, values, and venture context so the agent knows who it's serving.
- **Ungoverned execution** -- Agents do whatever you prompt them to. `mythos_guard` returns hard constraints and narrative boundaries before the agent acts.
- **No eval feedback loop** -- Agents can't tell if their output quality is degrading. `mythos_evaluate` returns pass rates, coherence scores, and diagnostics.
- **Zero cross-session memory** -- Agents don't remember what happened yesterday. `mythos_search` and `mythos_recap` give full memory retrieval across sessions.
- **Confabulation without grounding** -- Agents invent context. `mythos_consult` runs 12 independent governance perspectives against your intent before execution.
- **Approval gate** -- Agents execute without sign-off. `mythos_approve` lets the creator approve or reject a governed plan before execution begins.

## Tools

| Tool | Description |
|------|-------------|
| `mythos_getContext` | Load creator identity, voice, values, and venture context. Call at session start. |
| `mythos_guard` | Get active constraints, execution limits, and narrative boundaries for a venture. |
| `mythos_evaluate` | Check quality health of recent work. Returns pass rates, angel/demon scores, diagnostics. |
| `mythos_search` | Search creator memory -- facts, preferences, relationships, prior decisions. |
| `mythos_recap` | Get recent session history -- decisions, milestones, context from previous work. |
| `mythos_consult` | Run a full governance consultation. 12 archetypal seats evaluate your intent and produce an execution plan. |
| `mythos_approve` | Approve or reject a consultation plan before execution begins. |

## Install

```bash
npm install @myth-os/mcp
```

## Configure

Create `~/.mythos/config.json`:

```json
{
  "apiKey": "your-api-key",
  "deploymentUrl": "https://your-deployment.convex.site",
  "userId": "your-user-id"
}
```

Or use environment variables:

```bash
export MYTHOS_API_KEY="your-api-key"
export MYTHOS_DEPLOYMENT_URL="https://your-deployment.convex.site"
export MYTHOS_USER_ID="your-user-id"
export MYTHOS_WORLD_ID="optional-venture-id"
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mythos": {
      "command": "npx",
      "args": ["mythos-mcp"],
      "env": {
        "MYTHOS_API_KEY": "your-api-key",
        "MYTHOS_DEPLOYMENT_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
```

## Usage with Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "mythos": {
      "command": "npx",
      "args": ["mythos-mcp"],
      "env": {
        "MYTHOS_API_KEY": "your-api-key",
        "MYTHOS_DEPLOYMENT_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
```

## Usage with any MCP client

The server uses stdio transport. Run it as a subprocess:

```bash
npx mythos-mcp
```

It speaks the [Model Context Protocol](https://modelcontextprotocol.io/) standard. Any MCP-compatible client works.

## Tool details

### mythos_getContext

Returns the creator's narrative identity -- who they are, how they communicate, what they value. Optionally scoped to a specific venture/world.

```
Parameters:
  worldId? (string) -- Scope to a specific venture. Omit for creator-level context.
```

### mythos_guard

Returns governance constraints -- what the agent is allowed to do, execution limits, narrative boundaries, and active policies.

```
Parameters:
  worldId? (string) -- Scope to a specific venture.
```

### mythos_evaluate

Returns quality health metrics for a time window. Includes pass rates, angel/demon scoring (optimism vs skepticism), deterministic checks, and diagnostic messages.

```
Parameters:
  windowMinutes? (number) -- Lookback window. Default: 1440 (24 hours).
```

### mythos_search

Searches the creator's persistent memory. Returns memory cards with confidence scores, scoped to actor-level and world-level knowledge.

```
Parameters:
  limit?   (number) -- Max results. Default: 10.
  worldId? (string) -- Scope to a specific venture.
```

### mythos_recap

Returns recent session observations -- what happened across previous agent sessions. Gives cross-session continuity.

```
Parameters:
  limit?   (number) -- Number of recent entries. Default: 5.
  worldId? (string) -- Scope to a specific venture.
```

### mythos_consult

Runs a full governance octave -- 12 archetypal seats independently evaluate your intent, surface tensions, and produce a governed execution plan. Use before significant implementation work. Supports pause/resume when the system needs more context.

```
Parameters:
  intent?   (string) -- What you're planning to do.
  octaveId? (string) -- Resume a paused consultation (instead of intent).
  inputs?   (object) -- Context to fill gaps at pause point.
  worldId?  (string) -- Scope to a specific venture.
```

### mythos_approve

Approves or rejects a consultation plan that's waiting for creator review.

```
Parameters:
  octaveId (string)  -- The consultation to approve or reject.
  approved (boolean) -- true to proceed, false to reject.
```

## Architecture

The MCP server is a thin stdio-transport wrapper around the mythOS HTTP API. No Convex SDK dependency at runtime -- just `fetch()`. The backend runs on [Convex](https://convex.dev) (serverless, reactive).

```
Agent <--MCP/stdio--> mythos-mcp <--HTTP--> mythOS Convex backend
```

## Requirements

- Node.js >= 18
- A mythOS backend deployment (self-hosted or managed)
- API key with appropriate permissions

## License

MIT