# @owlmeans/viable-mcp

The MCP server a coding agent — Claude Code, Codex, GitHub Copilot or OpenCode — uses to build
full-stack web applications with the OwlMeans Viable platform. It runs over stdio through `npx`, signs
the person in with their browser, opens one platform session lazily and offers the platform's whole
tool catalogue: projects, user stories, conversions, local run, git, production, settings and the
generated application's users. Use it when an agent should drive Viable; to build your own host or
script instead, use the open-source
[`@owlmeans/viable-sdk`](https://github.com/owlmeans/common/tree/main/packages/viable-sdk) it is built on.

This package is closed-source and published as built code under the [OwlMeans Closed-Source Package
License](LICENSE). Issues: https://github.com/owlmeans/common/issues

## Installation

Nothing to install — the agent starts it:

```bash
npx -y @owlmeans/viable-mcp@^0.1.18
```

or, to embed the server in your own process:

```bash
bun add @owlmeans/viable-mcp@^0.1.18
```

## Concepts

- **Target** — where the generated project lives: `local` (this machine, the default) or `cloud`
  (a platform slot).
- **LLM mode** — who performs the platform's model calls: `cloud` (the platform, the default) or
  `local` (the delegated mode: the parent agent performs them through `next_task` /
  `submit_task_result`).
- **Harness** — which coding agent is on the other end (`claude-code`, `codex`, `copilot`,
  `opencode`); it decides the files `install_harness` writes.
- **Credentials** — an access token from `VIABLE_API_TOKEN` or `~/.owlmeans`; with neither, the first
  tool that needs the platform starts a browser sign-in. The environment always wins over the file.
- **Session** — one per attached project, opened by the first tool that needs it, never at startup.

## Usage

### Claude Code

```bash
npx -y @owlmeans/viable-mcp@^0.1.18 login           # once: browser sign-in → ~/.owlmeans
claude mcp add viable -- npx -y @owlmeans/viable-mcp@^0.1.18
```

Or connect Claude Code to the platform's hosted `/mcp` endpoint instead of a local process:

```bash
claude mcp add --transport http viable "$(npx -y @owlmeans/viable-mcp@^0.1.18 url)"
```

### Any MCP host (`.mcp.json` / `.vscode/mcp.json` style)

```json
{
  "mcpServers": {
    "viable": {
      "command": "npx",
      "args": ["-y", "@owlmeans/viable-mcp@^0.1.18-rc.46", "--harness", "claude-code"],
      "env": { "VIABLE_API_TOKEN": "${VIABLE_API_TOKEN:-}" }
    }
  }
}
```

Once connected, ask the agent to call `install_harness` — it writes the agent's worker subagent and
working rule into the project (see
[`@owlmeans/viable-harness`](https://www.npmjs.com/package/@owlmeans/viable-harness)).

### Embedding the server

```typescript
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { configHelper, makeViableMcpServer } from '@owlmeans/viable-mcp'

const cfg = await configHelper.readConfig(process.argv.slice(2), process.env)
const { server, close } = await makeViableMcpServer(cfg)
await server.connect(new StdioServerTransport())
process.on('SIGTERM', () => { void close() })
```

## CLI

| Command / option | Meaning |
|---|---|
| `login` · `logout` · `status` | Browser sign-in into `~/.owlmeans`; revoke and forget; report (stderr) |
| `url` | Print the platform's `/mcp` URL on stdout |
| `--api-url <url>` / `VIABLE_API_URL` | The platform's public API origin (self-hosted or development deployments) |
| `--target local\|cloud` / `VIABLE_TARGET` | Where the project lives (default `local`) |
| `--llm cloud\|local` / `VIABLE_LLM` | Who performs model calls (default `cloud`) |
| `--harness <name>` / `VIABLE_HARNESS` | The coding agent on the other end |
| `--project-dir <path>` / `VIABLE_PROJECT_DIR` | The local project directory (default: the working directory) |
| `OWLMEANS_CREDENTIALS` | Path of the credentials file (default `~/.owlmeans`) |

The token is never accepted on the command line — every process on the machine can read one.

## API

| Export | Description |
|---|---|
| `makeViableMcpServer(cfg)` → `{ server, close }` | The configured `McpServer` with the catalogue and the agent-setup tools registered |
| `configHelper.readConfig(argv, env)` · `configHelper.parseArgs(argv)` · `HELP` | Flags over environment over `~/.owlmeans` |
| `DEFAULT_API_URL` · `DEFAULT_TARGET` · `DEFAULT_LLM` · `CLIENT_ID` | Defaults and the static OAuth client id |
| `VERSION` | The version reported to the host — read from this package's manifest |
| `McpConfig` · `BuiltServer` | Types |

## Common pitfalls

- **stdout is the protocol.** Anything else the process prints goes to stderr; a host that sees a
  stray stdout line reports the server as broken.
- **Pin a caret range, never a tag.** `@next` resolves differently over time; the range resolves by
  version.
- **An empty `VIABLE_API_TOKEN` is ignored**, so `${VIABLE_API_TOKEN:-}` in a host configuration
  never shadows a signed-in `~/.owlmeans`.
- `VIABLE_API_URL` is the platform's public API origin (the host that serves `/mcp`), never a web
  app's `/api`.

## Related packages

- [`@owlmeans/viable-sdk`](https://github.com/owlmeans/common/tree/main/packages/viable-sdk) — the
  catalogue, sessions, executor and envelopes this server exposes
- [`@owlmeans/viable-harness`](https://www.npmjs.com/package/@owlmeans/viable-harness) — the
  agent-setup files and tools
- [`@owlmeans/cli-auth`](https://github.com/owlmeans/common/tree/main/packages/cli-auth) — the
  credentials file and device sign-in
- [`@owlmeans/viable-common`](https://github.com/owlmeans/common/tree/main/packages/viable-common) —
  the connector vocabulary

<!-- owlmeans:agent-guidance:start -->
## Agent guidance

This package ships embedded agent skills under `agent-meta/`. After installing your
`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
your project's skill store (`.agents/skills/`):

```sh
npx @owlmeans/agent-skills@^0.1.18
```

The embedded files are version-matched to this package release. Do not edit them
directly — they are regenerated on each publish. This package is closed-source; report a guidance
problem at https://github.com/owlmeans/common/issues.
<!-- owlmeans:agent-guidance:end -->