# Plugins

Install the Lys plugin in Claude Code or Codex and authenticate its remote MCP connection.

The Lys plugin connects the host to Lys over Streamable HTTP and supplies skills for its current schemas. Both host packages are version 0.1.0. Host OAuth establishes an app agent answering to the person who consented; that agent still needs its own grants.

## Install in Claude Code

From the root of a Lys repository checkout, add the local marketplace and install the plugin:

**Install in Claude Code**

```bash
claude plugin marketplace add ./
claude plugin install lys@lys-local
```


The marketplace is `lys-local`; its Claude Code package is `plugin/`. Inspect the connection before consent:

**Inspect Claude Code connection status**

```bash
claude mcp list
```


**A connection requiring authentication**

```text
plugin:lys:lys: https://lys.ablative.com.au/api/mcp (HTTP) - ! Needs authentication
```


Open a new host session, open `/mcp`, choose the Lys server and Authenticate, then complete the Lys consent screen. Run `/lys:setup` to read the tool list and the caller's admitted discovery.

### Claude Code skills

- `access`: Give, inspect and explain Lys access through grants, roles, requests and reviews.
- `agents`: Manage Lys agent profiles, harnesses, skills, budgets, certificates and launches.
- `apps`: Manage Lys apps, schema registration, approvals, placements and OAuth connections.
- `draft-workflow`: Record, inspect and decide Lys directory and product drafts without confusing approval with execution.
- `goals`: Manage Lys goals, alarms and scheduled delivery with occurrence evidence.
- `identity`: Read and manage Lys identities, own agents, accounts and sessions.
- `lys`: Operate Lys through its four MCP tools, live schemas, grants and named refusals. Use before Lys route work.
- `network`: Read Lys computers, runners, client artifacts and join evidence.
- `runtime`: Operate Lys seats and runtime sessions with delivery receipts and event signals.
- `secrets`: Manage Lys secret metadata and handle scope without revealing secret values.
- `service`: Inspect Lys service contracts, health, configuration, receipts, setup and change signals.
- `teams`: Manage Lys team membership, nesting and the caller-visible team tree.
- `words`: Read, preview and revise Lys instruction slots and named templates.


### Claude Code commands

- `/lys:capabilities`: Show the routes, resources and actions this Lys connection currently holds.
- `/lys:drafts`: List, prepare or decide Lys drafts through the correct draft family and responsible authority.
- `/lys:give-access`: Prepare and apply an authorized Lys grant, then verify its receipt and recipient access.
- `/lys:my-agents`: List the agents visible to the current Lys caller, with honest authentication limits.
- `/lys:read-route`: Read a declared Lys route using its current schema and the caller's authority.
- `/lys:setup`: Verify the Lys plugin connection, live tool list and admitted discovery without changing state.
- `/lys:whoami`: Identify the caller of this Lys connection without confusing a person and an agent.


## Install in Codex

From the same repository root, add the Codex marketplace and plugin:

**Install in Codex**

```bash
codex plugin marketplace add ./
codex plugin add lys@lys-local
```


The Codex marketplace manifest is `.agents/plugins/marketplace.json`; it selects `plugins/lys/`.

- `Claude Code`: Lys version 0.1.0, enabled.
- `Codex`: Lys version 0.1.0, enabled.


Inspect the server's authentication state:

**Inspect Codex connection status**

```bash
codex mcp list
```


- `Server`: lys
- `URL`: https://lys.ablative.com.au/api/mcp
- `Auth`: Not logged in


Begin login and complete the person's consent at Lys:

**Begin Lys consent in Codex**

```bash
codex mcp login lys
```


In a new session, invoke the Lys `setup` skill. Use the skill picker when another plugin has the same short name.

### Codex skills

- `access`: Give, inspect and explain Lys access through grants, roles, requests and reviews.
- `agents`: Manage Lys agent profiles, harnesses, skills, budgets, certificates and launches.
- `apps`: Manage Lys apps, schema registration, approvals, placements and OAuth connections.
- `capabilities`: Show the routes, resources and actions this Lys connection currently holds.
- `draft-workflow`: Record, inspect and decide Lys directory and product drafts without confusing approval with execution.
- `drafts`: List, prepare or decide Lys drafts through the correct draft family and responsible authority.
- `give-access`: Prepare and apply an authorized Lys grant, then verify its receipt and recipient access.
- `goals`: Manage Lys goals, alarms and scheduled delivery with occurrence evidence.
- `identity`: Read and manage Lys identities, own agents, accounts and sessions.
- `lys`: Operate Lys through its four MCP tools, live schemas, grants and named refusals. Use before Lys route work.
- `my-agents`: List the agents visible to the current Lys caller, with honest authentication limits.
- `network`: Read Lys computers, runners, client artifacts and join evidence.
- `read-route`: Read a declared Lys route using its current schema and the caller's authority.
- `runtime`: Operate Lys seats and runtime sessions with delivery receipts and event signals.
- `secrets`: Manage Lys secret metadata and handle scope without revealing secret values.
- `service`: Inspect Lys service contracts, health, configuration, receipts, setup and change signals.
- `setup`: Verify the Lys plugin connection, live tool list and admitted discovery without changing state.
- `teams`: Manage Lys team membership, nesting and the caller-visible team tree.
- `whoami`: Identify the caller of this Lys connection without confusing a person and an agent.
- `words`: Read, preview and revise Lys instruction slots and named templates.


The Claude Code command workflows are skills in the Codex package; it has no separate command directory.

## Connect the MCP server

Both manifests select `config/lys-mcp.json`, which declares an HTTP server at `https://lys.ablative.com.au/api/mcp`. The host owns OAuth and the consent flow. This plugin needs no local Lys executable, SSH access, private signing key or manually supplied bearer token.

- `Transport`: Streamable HTTP to https://lys.ablative.com.au/api/mcp, declared in config/lys-mcp.json for both hosts.
- `Authentication`: Host-managed OAuth and Lys consent. Codex requests authentication on install; Claude Code offers Authenticate in /mcp.
- `Caller`: An app agent answering to the consenting person. Product grants belong to that agent; consent does not copy the person’s rights.
- `Discovery`: Read what-can-I-do and the live OpenAPI before assembling route bodies. Discovery remains subject to the caller’s admitted scope.
- `Local bridge`: lys mcp is a separate signed bridge for a numeric loopback HTTP URL. It is not the launcher for this remote HTTPS plugin.


### Tools returned by tools/list

- `what-can-I-do`: List the routes, resources and actions this connection may reach under its live grants.
- `read`: Read through an existing HTTP route with the caller's credentials and admission.
- `change`: Change through an existing HTTP route. Its validation, authority checks and refusals apply unchanged.
- `drafts`: Ask an existing draft route with the caller's credentials. This transport grants no draft authority.


On an admitted connection, `what-can-I-do` returns routes and live grants. Read the current operation schema before supplying a route or body. [MCP](/lys/reference/mcp/) describes the inputs and the separate signed local bridge.

## Keep the caller's authority explicit

The OAuth connection is an app agent. Personal routes and directory draft decisions require a person connection; consenting does not let the app agent impersonate that person. Directory draft creation requires an agent signature, which the HTTP plugin does not supply. Use a correctly authenticated connection for that operation.

The `drafts` tool is restricted to directory `/drafts` routes. Product drafts use `/product-drafts` through `read` or `change`. Approval and execution are separate results; keep the receipt for each.

## Answer a refusal

- `NotSignedIn`: Exact refusal reason: NotSignedIn: sign in through the configured issuer first. Complete host authentication before asking for discovery.


**Missing authentication**

```json
{"refusal":"NotSignedIn","reason":"NotSignedIn: sign in through the configured issuer first","fields":[]}
```


An unauthenticated POST to `/api/mcp` receives status 401 and the authentication metadata challenge:

**Unauthenticated MCP challenge**

```text
www-authenticate: Bearer resource_metadata="https://lys.ablative.com.au/.well-known/oauth-protected-resource"
```


Complete host authentication through the intended connection. Preserve an uncertain operation's identifier and reconcile it before attempting another change.

## Companion roles

Claude Code includes `access-reader` and `draft-preparer`. They read authority and prepare proposed drafts within the caller's grants. The Codex package supplies `lys-access-reader` and `lys-draft-preparer` companion role files; its plugin manifest does not register them automatically.