Cortex Plugins

Name: Cortex Plugins
Rating: 3.5 (1 reviews)
Author: Versatly

By Versatly 👁 32 views ▲ 0 votes

Cortex connector plugins for Cursor, Codex, Hermes, and OpenClaw — remote MCP (OAuth 2.1) and headless agent enrollment

GitHub

Install

npm install     #

Configuration Example

{
  "mcpServers": {
    "cortex": {
      "url": "https://cortex.versatlyai.com/api/mcp"
    }
  }
}

README

# Cortex Connector Plugins

Production connector packages that let agents and editors **without the Cortex
desktop app** connect to a Cortex workspace.

Two connection surfaces are covered:

1. **Remote MCP** — Cortex exposes a streamable-HTTP MCP endpoint at
   `https://cortex.versatlyai.com/api/mcp`, protected by **OAuth 2.1 with
   dynamic client registration** (Clerk authorization server, RFC 9728
   protected-resource metadata). No API keys exist or are ever required.
2. **Headless agent enrollment** — long-running agent runtimes (Hermes,
   OpenClaw) enroll a dedicated, owner-approved identity through the `cortex`
   CLI (`npx @versatly/cortex`), then talk to the Buzz relay directly.

## Plugin matrix

| Package | Directory | Client | Surface | Transport | Auth |
|---|---|---|---|---|---|
| [`@versatly/cortex-cursor`](cursor/) | `cursor/` | Cursor | Remote MCP | Streamable HTTP | OAuth 2.1 (dynamic client registration) |
| [Codex docs](codex/) | `codex/` | Codex (OpenAI) | Remote MCP | Streamable HTTP | OAuth 2.1 (dynamic client registration) |
| [`@versatly/cortex-codex-proxy`](codex/proxy/) | `codex/proxy/` | Codex (stdio fallback) | Remote MCP via local proxy | stdio ⇄ Streamable HTTP | OAuth 2.1 (dynamic client registration) |
| [`@versatly/cortex-hermes-plugin`](hermes/) | `hermes/` | Hermes agent runtime | Headless enrollment + gateway env | Buzz relay (WebSocket) | Owner-approved enrollment key (generated locally, never leaves the machine) |
| [`@versatly/cortex-openclaw-plugin`](openclaw/) | `openclaw/` | OpenClaw ACP runtime | Deterministic one-step apply | Buzz relay (WebSocket) | Owner-approved enrollment key (generated locally, never leaves the machine) |

## Quickstart per client

### Cursor

One-click (deeplink):

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=cortex&config=eyJ1cmwiOiJodHRwczovL2NvcnRleC52ZXJzYXRseWFpLmNvbS9hcGkvbWNwIn0=
```

Or add to `.cursor/mcp.json` (project) / `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "cortex": {
      "url": "https://cortex.versatlyai.com/api/mcp"
    }
  }
}
```

Cursor opens the browser for the OAuth 2.1 flow on first use. See
[`cursor/README.md`](cursor/README.md).

### Codex (OpenAI)

```bash
codex mcp add cortex --url https://cortex.versatlyai.com/api/mcp
```

or in `~/.codex/config.toml`:

```toml
[mcp_servers.cortex]
url = "https://cortex.versatlyai.com/api/mcp"
```

If your Codex build only supports stdio MCP servers, use the bundled proxy:

```toml
[mcp_servers.cortex]
command = "npx"
args = ["-y", "@versatly/cortex-codex-proxy"]
```

See [`codex/README.md`](codex/README.md).

### Hermes

```bash
npx @versatly/cortex-hermes-plugin <https://cortex.versatlyai.com/connect/...> --name my-hermes-agent
```

Detects the Hermes installation, runs headless enrollment through the `cortex`
CLI, waits for the workspace owner's approval, and writes the Cortex gateway
environment file for the selected Hermes profile. See
[`hermes/README.md`](hermes/README.md).

### OpenClaw

```bash
npx @versatly/cortex-openclaw-plugin <https://cortex.versatlyai.com/connect/...> --name my-openclaw-agent --apply
```

Verifies the OpenClaw runtime, then delegates to the deterministic one-step
`cortex agents connect <url> --apply` flow (owner-approved, resumable,
idempotent). See [`openclaw/README.md`](openclaw/README.md).

## Security model

- **No secrets in this repository.** Nothing here embeds, requires, or stores
  an API key.
- Remote MCP access is OAuth 2.1 only: clients discover the authorization
  server via RFC 9728 protected-resource metadata, register dynamically, and
  complete an authorization-code + PKCE flow in the user's browser.
- Agent enrollment keys are generated **locally** by the `cortex` CLI, stored
  in an owner-only credential file (`0600` on POSIX, exact current-user DACL on
  Windows), and are never printed, uploaded, or copied by these plugins.
- Enrollment always requires explicit approval by the workspace owner
  (Cortex Desktop or the Cortex web control plane) before any access exists.

See [SECURITY.md](SECURITY.md) for reporting.

## Development

```bash
npm install     # installs workspace dependencies
npm run lint    # syntax + package metadata checks
npm test        # runs every package's node --test suite
```

Node.js >= 20 is required. All packages are plain modern Node ESM with JSDoc
types — no build step.

## Repository layout

```text
cursor/     Cursor MCP config package + directory-submission metadata
codex/      Codex MCP docs + connector-submission metadata
codex/proxy stdio -> streamable-HTTP OAuth proxy package
hermes/     Hermes detection + enrollment + gateway env plugin
openclaw/   OpenClaw detection + one-step apply plugin
```

## License

MIT © Versatly. See [LICENSE](LICENSE).

integration