# Plugin catalog

> Published protocol and provider plugins (OpenAPI, GraphQL, MCP, file-secrets, keychain, 1Password, Google, WorkOS Vault) and how `examples/all-plugins` wires them together.

- Repository: RhysSullivan/executor
- GitHub: https://github.com/RhysSullivan/executor
- Human docs: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052
- Complete Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/llms-full.txt

## Source Files

- `examples/all-plugins/src/main.ts`
- `examples/all-plugins/package.json`
- `packages/plugins/openapi/package.json`
- `packages/plugins/graphql/package.json`
- `packages/plugins/mcp/package.json`
- `packages/plugins/file-secrets/package.json`
- `packages/core/integrations-registry/package.json`

---

---
title: "Plugin catalog"
description: "Published protocol and provider plugins (OpenAPI, GraphQL, MCP, file-secrets, keychain, 1Password, Google, WorkOS Vault) and how `examples/all-plugins` wires them together."
---

Executor extends through npm packages under `packages/plugins/*`. Each plugin is a `definePlugin` factory: protocol plugins register integrations and produce per-connection tools; credential plugins register `CredentialProvider` backends that store connection values. Host apps declare the plugin list in `executor.config.ts` via `defineExecutorConfig`; SDK embedders pass the same factories to `createExecutor({ plugins })`. The `examples/all-plugins` example composes every published plugin into one executor and walks integration registration, connection creation, tool listing, execution, and shutdown.

## Plugin roles

| Role | Plugins | What they contribute |
| --- | --- | --- |
| Protocol / integration | `@executor-js/plugin-openapi`, `@executor-js/plugin-graphql`, `@executor-js/plugin-mcp`, `@executor-js/plugin-google` | Integration catalog entries, per-connection tool production, `invokeTool`, auth template descriptors |
| Credential provider | `@executor-js/plugin-file-secrets`, `@executor-js/plugin-keychain`, `@executor-js/plugin-onepassword`, `@executor-js/plugin-workos-vault` | Writable (or read-only) `CredentialProvider` backends; connection values resolve through these at invoke time |

<Note>
In v2, a connection **is** the credential. There is no separate secret store. The connection row references a `ProviderKey` and opaque `ProviderItemId`; the provider plugin reads and writes the value.
</Note>

## Published packages

| Package | Plugin ID | Provider key | Primary extension methods |
| --- | --- | --- | --- |
| `@executor-js/plugin-openapi` | `openapi` | — | `previewSpec`, `addSpec`, `updateSpec`, `configure`, `configureAuth` |
| `@executor-js/plugin-graphql` | `graphql` | — | `addIntegration`, `configure`, `configureAuth`, `probeEndpoint` |
| `@executor-js/plugin-mcp` | `mcp` | — | `addServer`, `probeEndpoint`, `configureAuth`, `getServer` |
| `@executor-js/plugin-google` | `google` | — | `addBundle`, `updateBundle`, `removeBundle`, `configure` |
| `@executor-js/plugin-file-secrets` | `fileSecrets` | `file` | `filePath` (auth file location) |
| `@executor-js/plugin-keychain` | `keychain` | `keychain` | `isSupported`, `displayName`, `has` |
| `@executor-js/plugin-onepassword` | `onepassword` | `onepassword` | `configure`, `status`, `getConfig`, `listVaults`, `resolveSecret` |
| `@executor-js/plugin-workos-vault` | `workosVault` | `workos-vault` | `providerKey` |

Protocol plugins also expose `integrationPresets` (OpenAPI ships Stripe, GitHub REST, Vercel, Cloudflare, and others; Google ships a discovery-bundle preset). Credential plugins auto-register at `createExecutor` startup via `plugin.credentialProviders`; inline `config.providers` register first and win as the default writable store.

## SDK plugin vs HTTP plugin

Protocol plugins ship two entry points:

| Import path | Use when |
| --- | --- |
| `@executor-js/plugin-openapi` (and siblings) | SDK embedders, scripts, tests |
| `@executor-js/plugin-openapi/api` | Host runtimes that mount HTTP routes (`routes`, `handlers`, `extensionService`) |

The HTTP variant spreads the SDK plugin and adds Effect HTTP API groups. SDK-only consumers never load `@executor-js/api`. Credential plugins (`keychain`, `file-secrets`) expose only the root and `./promise` subpaths; they have no HTTP surface.

```text
  executor.config.ts                    createExecutor({ plugins })
         |                                        |
         v                                        v
  *HttpPlugin() from ./api              SDK plugin factories
  (local, cloud, self-host)             (examples/all-plugins)
         |                                        |
         +------------------+---------------------+
                            v
                   definePlugin factory
                            |
            +---------------+---------------+
            |               |               |
       extension      credentialProviders   storage
     (executor.openapi)  (auto-register)   (plugin blobs)
```

## Plugin contract

Every plugin factory returns an object shaped by `definePlugin`:

<ParamField body="id" type="string" required>
Stable plugin identifier. Becomes `executor[id]` on the merged executor surface (for example `executor.openapi`, `executor.mcp`).
</ParamField>

<ParamField body="extension" type="(ctx) => TExtension">
Plugin-specific API surfaced on the executor. Integration plugins register catalog entries here; credential plugins expose configuration helpers.
</ParamField>

<ParamField body="credentialProviders" type="CredentialProvider[] | Effect">
Optional. Registered at startup. Keychain probes write capability before registering; WorkOS Vault requires `credentials` or a pre-built `client`.
</ParamField>

<ParamField body="storage" type="(deps) => TStore">
Optional typed store backed by host-owned blob and plugin storage facades.
</ParamField>

<ParamField body="routes / handlers / extensionService" type="HTTP API">
Present only on `*HttpPlugin` variants for host mounting.
</ParamField>

<ParamField body="close" type="() => Effect">
Optional lifecycle hook. MCP tears down connection pools on shutdown.
</ParamField>

After `createExecutor`, each plugin extension is reachable as `executor[pluginId]`. TypeScript preserves the merged tuple type when plugins are passed `as const`.

## Runtime plugin lists

Hosts pick plugins for their deployment context:

<Tabs>
<Tab title="Local (`apps/local`)">

```ts
openApiHttpPlugin(),
googleHttpPlugin(),
microsoftHttpPlugin(),
mcpHttpPlugin({ dangerouslyAllowStdioMCP: true }),
graphqlHttpPlugin(),
keychainPlugin(),
fileSecretsPlugin(),
onepasswordHttpPlugin(),
desktopSettingsPlugin({ webBaseUrl }),
```

Stdio MCP is enabled for trusted single-user local use. Keychain, file-secrets, and 1Password back local credential storage.

</Tab>
<Tab title="Cloud (`apps/cloud`)">

```ts
openApiHttpPlugin(),
googleHttpPlugin(),
microsoftHttpPlugin(),
mcpHttpPlugin({ dangerouslyAllowStdioMCP: false }),
graphqlHttpPlugin(),
workosVaultPlugin({ credentials: workosCredentials }),
```

Multi-tenant cloud omits stdio MCP and OS-local secret backends. WorkOS Vault is the cloud credential provider.

</Tab>
<Tab title="SDK example (`examples/all-plugins`)">

```ts
keychainPlugin(),
fileSecretsPlugin(),
onepasswordPlugin(),
googlePlugin(),
graphqlPlugin(),
mcpPlugin({ dangerouslyAllowStdioMCP: false }),
openApiPlugin(),
// workosVaultPlugin({ credentials: { apiKey, clientId } }),
```

Uses SDK factories (not HTTP variants) plus an inline in-memory provider for script-friendly credential writes.

</Tab>
</Tabs>

## `examples/all-plugins` wiring

The example (`@executor-js/example-all-plugins`) demonstrates the v2 SDK bootstrap shape without HTTP or tenant persistence:

<Steps>
<Step title="Install dependencies and run">

```bash
cd examples/all-plugins
bun run start
```

Runs `src/main.ts` against the SDK ephemeral in-memory FumaDB backend.

</Step>

<Step title="Compose plugins and providers">

```ts
const executor = yield* createExecutor({
  tenant: Tenant.make("example-tenant"),
  plugins: [
    keychainPlugin(),
    fileSecretsPlugin(),
    onepasswordPlugin(),
    googlePlugin(),
    graphqlPlugin(),
    mcpPlugin({ dangerouslyAllowStdioMCP: false }),
    openApiPlugin(),
  ],
  providers: [memoryProvider],
  onElicitation: "accept-all",
});
```

`providers` registers the in-memory store first so inline connection `value` writes land there by default.

</Step>

<Step title="Register integrations and connections">

OpenAPI: `executor.openapi.addSpec({ spec, slug, baseUrl, authenticationTemplate })`, then `executor.connections.create({ owner, name, integration, template, value })`.

GraphQL: `executor.graphql.addIntegration({ endpoint, slug, introspectionJson })`, then a `none`-template connection with an empty value.

</Step>

<Step title="List, execute, and shut down">

```ts
yield* executor.tools.list({ integration });
yield* executor.execute(toolAddress, {});
yield* executor.close();
```

OpenAPI and GraphQL flows run end-to-end. Keychain, 1Password, MCP, Google, and WorkOS Vault extensions are wired but skipped unless external infra is available.

</Step>
</Steps>

## Protocol plugins

### OpenAPI (`@executor-js/plugin-openapi`)

Turns OpenAPI 3.x specs into integration catalog entries. Each operation becomes a tool; tool addresses follow `tools.<integration>.<owner>.<connection>.<operationId>`.

| Method | Purpose |
| --- | --- |
| `previewSpec(spec)` | Inspect servers, auth schemes, operation count before adding |
| `addSpec(config)` | Register integration; `spec` accepts `{ kind: "blob", value }` or `{ kind: "url", url }` |
| `updateSpec(slug, input?)` | Refresh spec in place; returns added/removed tool names |
| `configure` / `configureAuth` | Merge or replace `authenticationTemplate` entries |

Auth templates use placement-based descriptors from `@executor-js/sdk/http-auth` (headers, query, bearer, OAuth2). Annotations (for example `requiresApproval` on POST/DELETE) resolve at read time via `resolveAnnotations`.

### GraphQL (`@executor-js/plugin-graphql`)

Registers GraphQL endpoints by introspection (live or canned `introspectionJson`). Query fields map to tools; mutations default to requiring approval.

| Method | Purpose |
| --- | --- |
| `addIntegration({ endpoint, slug, introspectionJson, authenticationTemplate })` | Register catalog entry and materialize tools |
| `configure` / `configureAuth` | Update endpoint metadata or merge auth methods |
| `probeEndpoint` | Pre-flight connectivity and schema discovery |

### MCP (`@executor-js/plugin-mcp`)

Proxies upstream MCP servers into the unified tool catalog. Remote transport uses HTTP; stdio spawns a local subprocess.

| Transport | Input shape | Constraint |
| --- | --- | --- |
| `remote` | `{ endpoint, remoteTransport?, headers?, authenticationTemplate? }` | Safe for multi-tenant hosts |
| `stdio` | `{ command, args?, env?, cwd? }` | Requires `dangerouslyAllowStdioMCP: true` |

`addServer` registers the integration; `probeEndpoint` checks connectivity, OAuth requirements, and tool count before add. MCP tool annotations carry an opaque `mcp` envelope with the upstream tool name for invoke dispatch.

<Warning>
Stdio MCP inherits `process.env` and spawns subprocesses. Enable only in trusted single-user contexts (local daemon). Cloud and self-host configs set `dangerouslyAllowStdioMCP: false`.
</Warning>

### Google (`@executor-js/plugin-google`)

Wraps the OpenAPI plugin backing. Fetches Google API Discovery documents, converts them to OpenAPI, and registers a bundled integration.

| Method | Purpose |
| --- | --- |
| `addBundle({ urls, slug?, name?, baseUrl? })` | Fetch discovery docs and register tools |
| `updateBundle(slug, { urls? })` | Refresh discovery bundle |
| `configure(slug, { authenticationTemplate, mode? })` | Merge or replace auth methods |

Depends on `@executor-js/plugin-openapi` internally for compilation and invocation.

## Credential provider plugins

### File secrets (`@executor-js/plugin-file-secrets`)

Stores connection values in a flat JSON file (`auth.json`) under the XDG data directory (default `~/.local/share/executor/auth.json`). File permissions are restricted (`0o600` file, `0o700` directory). Override the directory with `fileSecretsPlugin({ directory })`.

Provider key: `file`. Extension exposes `executor.fileSecrets.filePath`.

### Keychain (`@executor-js/plugin-keychain`)

Uses `@napi-rs/keyring` for OS keychain storage (macOS Keychain, Windows Credential Manager, Linux Secret Service). Probes write capability at startup; skips registration when the keychain is unreachable (headless CI, WSL without secret-service).

Provider key: `keychain`. Service name defaults to `"executor"`; override with `keychainPlugin({ serviceName })`.

### 1Password (`@executor-js/plugin-onepassword`)

Resolves secrets from 1Password vaults via desktop-app or service-account auth. Configuration is owner-partitioned blob storage. Exposes executor static tools (`status`, `configure`, `listVaults`, `getConfig`) for setup without leaking secret values in tool output.

Provider key: `onepassword`. Configure with `executor.onepassword.configure({ auth, vaultId, name })` before connections can resolve 1Password-backed values.

### WorkOS Vault (`@executor-js/plugin-workos-vault`)

Cloud-hosted credential backend using the WorkOS Vault API. Requires `workosVaultPlugin({ credentials: { apiKey, clientId } })` or a pre-built `client` for tests.

Provider key: `workos-vault`. Used by `apps/cloud`; omitted from local single-user configs in favor of keychain and file backends.

## Package exports

Integration plugins share a common export layout:

| Subpath | Contents |
| --- | --- |
| `.` | Promise-mode entry (default for `createExecutor` promise wrappers) |
| `./core` | Effect-native plugin factory |
| `./api` | HTTP-augmented `*HttpPlugin` for host runtimes |
| `./react` / `./client` | Web UI plugin client components |
| `./presets` | Integration preset catalog entries |
| `./testing` | Test helpers and fixtures |

Credential plugins export `.` and `./promise` (and `./core` where published). Install with the package manager of your choice:

<CodeGroup>
```bash title="bun"
bun add @executor-js/sdk @executor-js/plugin-openapi @executor-js/plugin-mcp
```

```bash title="npm"
npm install @executor-js/sdk @executor-js/plugin-openapi @executor-js/plugin-mcp
```
</CodeGroup>

## Choosing plugins

```mermaid
flowchart TB
  subgraph embed["SDK embedder"]
    CE["createExecutor({ plugins })"]
  end
  subgraph host["Host runtime"]
    EC["executor.config.ts"]
    HP["*HttpPlugin from ./api"]
  end
  subgraph protocols["Protocol plugins"]
    OAPI["openApiPlugin / openApiHttpPlugin"]
    GQL["graphqlPlugin / graphqlHttpPlugin"]
    MCP["mcpPlugin / mcpHttpPlugin"]
    GOOG["googlePlugin / googleHttpPlugin"]
  end
  subgraph creds["Credential plugins"]
    MEM["inline providers[]"]
    FILE["fileSecretsPlugin"]
    KEY["keychainPlugin"]
    OP["onepasswordPlugin"]
    WV["workosVaultPlugin"]
  end
  CE --> protocols
  CE --> creds
  EC --> HP
  HP --> protocols
  HP --> creds
  OAPI --> INT["integrations.register + tools per connection"]
  GQL --> INT
  MCP --> INT
  GOOG --> OAPI
  FILE --> PROV["providers.list → connection resolve"]
  KEY --> PROV
  OP --> PROV
  WV --> PROV
  MEM --> PROV
```

<AccordionGroup>
<Accordion title="Other monorepo plugins (not in all-plugins example)">

`@executor-js/plugin-microsoft` follows the Google pattern (discovery to OpenAPI). `@executor-js/plugin-encrypted-secrets` provides an encrypted local store (`encrypted` provider key). `@executor-js/plugin-desktop-settings` is a local-only server plugin for desktop app settings. These ship in host configs but are outside the `examples/all-plugins` dependency set.

</Accordion>

<Accordion title="Integrations registry (separate from plugins)">

`@executor-js/integrations-registry` fetches a curated integration catalog from `https://integrations.sh/api.json` (overridable via `EXECUTOR_INTEGRATIONS_URL`). It is not a plugin; `apps/local` runs it as a background refresh layer for the web UI add-integration flow.

</Accordion>
</AccordionGroup>

## Verification

After wiring plugins, confirm registration:

```bash
cd examples/all-plugins && bun run start
```

Expected console sections: registered provider keys (`memory`, `file`, `keychain`, `onepassword` when reachable), OpenAPI integration `example-api` with four tools, GraphQL integration `example-graphql` with query/mutation tools, and a clean `executor.close()`.

For host runtimes, `executor providers` (CLI) or `GET /providers` (HTTP API) lists registered provider keys. Missing provider errors surface as `CredentialProviderNotRegisteredError` at connection resolve time.

## Related pages

<CardGroup>
<Card title="Embed with the SDK" href="/embed-sdk">
Compose `createExecutor` with plugins, register integrations, and invoke tools from application code.
</Card>
<Card title="Configure credentials" href="/configure-credentials">
Connection payloads, OAuth flows, and placement-based auth templates across credential providers.
</Card>
<Card title="Add integrations" href="/add-integrations">
Add OpenAPI, GraphQL, and MCP sources from the web UI or CLI after plugins are loaded.
</Card>
<Card title="SDK quickstart example" href="/sdk-quickstart-example">
Smaller walkthrough focused on OpenAPI and in-memory credentials.
</Card>
</CardGroup>