# The Agent Plugin

The Agent Plugin gives an agent a place to put the HTML it just wrote. It is an
[Agent Plugins 1.0.0](https://agent-plugins.org) bundle (a `plugin.json`
carrying identity, an `mcp.json` describing the MCP server, and one skill),
portable across ChatGPT, Codex, Cursor, Copilot, Kiro, and VS Code. Claude
Code reads the same three pieces under different names, so the bundle also
carries them in Claude's layout; the two manifests are held equal on every
build, and the skill is shared rather than duplicated.

## What it gives an agent

**The four tools**: `publish`, `update`, `list`, `unpublish`. `publish` takes
the HTML **as a string rather than a path**, so a page the agent just composed
reaches a live URL in one tool call, no temp file in between.

**The skill** is the other half: it tells an agent that Emits exists, when
reaching for it is the right move, and how to fall back to
[the CLI](/docs/cli) in a client that loaded the skill but not the server.

The bundle wires up the **local** stdio server. The same four tools are also
hosted at `https://api.emits.app/mcp` for clients that cannot launch a
subprocess (see [MCP](/docs/mcp)).

## Install

### Claude Code

```bash
claude plugin marketplace add raymond-UI/emits-plugin
claude plugin install emits@mzed
```

### Any other client

Point the client's MCP configuration at the CLI's server:

```json
{
  "mcpServers": {
    "emits": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mzedstudio/emits-cli", "mcp"]
    }
  }
}
```

Then log in once so the server has a credential to publish with:

```bash
npx -y @mzedstudio/emits-cli login
```

### A client that cannot launch a subprocess

Use the remote server at `https://api.emits.app/mcp`. There is no `login`
step: the client registers itself, sends its human to a browser consent
screen, and receives a scoped OAuth token: `pages:read` covers `list`, and
`pages:write` covers the other three tools. The handshake is described in
[MCP](/docs/mcp#the-remote-server).

## Auth

The plugin ships no credentials and hardcodes no token. The local MCP server
reads the same stored credential the CLI writes, so `emit login` once serves
both, and tokens stay on your machine. See [authentication](/docs/auth) for
the model behind the tokens themselves.

## Source

The plugin is generated from the CLI's own skill renderer (the same document
`emit skill` prints), so the plugin and the CLI cannot describe the product
differently. Every build validates the bundle against the vendored Agent
Plugins 1.0.0 schemas.