> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artifacta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Install as a Codex Plugin

> Install Artifacta in Codex with hosted OAuth MCP, persistent-output skills, and verified transcript capture.

The **Artifacta Codex plugin** is the recommended setup for Codex users. It
bundles the hosted Artifacta MCP connection, reusable persistence skills, and
verified Codex transcript capture. Authentication happens through browser
OAuth—there is no API key to copy and no local Artifacta process to run.

<Note>
  The plugin connects to `https://mcp.artifacta.io/mcp`. For CI, restricted
  networks, or explicit API-key control, use the
  [local stdio setup](/mcp/overview#codex-local-stdio) instead.
</Note>

## Prerequisites

* Codex installed and able to run `codex plugin`.
* A free Artifacta account. Sign up at
  [app.artifacta.io/signup](https://app.artifacta.io/signup).

## Install

Add the Artifacta marketplace, then install the plugin:

```bash theme={null}
codex plugin marketplace add SagaPeak/artifacta-mcp
codex plugin add artifacta@artifacta
```

Authenticate the bundled MCP server:

```bash theme={null}
codex mcp login artifacta
```

The login command opens Artifacta in your browser. Sign in, choose the
permissions you want to grant, and authorize the connection.

Start a **new Codex thread** after installation so Codex loads the plugin's
skills and hooks. Open `/hooks`, review the bundled Artifacta hook, and trust
its current definition if you want to use one-shot automatic transcript
capture. Codex skips untrusted non-managed hooks.

## Verify the install

Check the installed version:

```bash theme={null}
codex plugin list
```

The listing should show `artifacta@artifacta` as installed and enabled. The
current plugin version is `1.1.0`.

In the new thread, ask:

> "Use Artifacta MCP `whoami` and report my tenant and plan."

Codex should call `whoami` without asking for an API key.

## What the plugin adds

* **Hosted Artifacta MCP** — read, upload, retrieve, share, delete, and session
  tools, authorized by the OAuth tier you choose.
* **`persisting-outputs` skill** — stores reports, datasets, generated files,
  and other run outputs through Artifacta MCP.
* **`capture-transcript` skill** — locates and verifies the current Codex
  rollout, creates a private snapshot, and uploads it through
  `store_artifact`.

The hosted MCP server cannot read a path on your computer. The skills send
small local files as base64 `content`; they do not pass a local path to the
remote server and do not invoke the local Artifacta CLI.

## Capture a Codex transcript

For an immediate snapshot, ask:

> "Use Artifacta to capture this Codex session's transcript."

The skill verifies the live rollout before copying or uploading it. The
snapshot is tagged with `metadata.type=transcript` and
`metadata.capture=snapshot`.

For one capture at the current thread's next `Stop`, include the explicit
flag:

> "Use Artifacta to capture this Codex session's transcript --automatic."

`--automatic` is one-shot consent for this thread. It does **not** enable
every-turn capture, future-thread capture, or an ongoing background uploader.
The trusted Stop hook requests one authenticated continuation, which uploads
the snapshot through Artifacta MCP.

<Warning>
  Artifacta does not redact transcript snapshots. They can contain prompts, tool
  arguments, tool results, credentials, and other sensitive text. Review what
  your session contains before requesting capture.
</Warning>

See [Store session transcripts](/guides/transcripts#codex-plugin) for capture
metadata, retrieval, and limitations.

## OAuth permissions

Artifacta permissions are nested:
`artifacts:read` ⊆ `artifacts:write` ⊆ `artifacts:destroy`.

| Grant         | Authorized actions                                                                                    |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| **Read**      | Call `whoami`; list, inspect, and download artifacts; list sessions.                                  |
| **+ Write**   | Upload with `store_artifact` or the large-file flow.                                                  |
| **+ Destroy** | Mint public links with `create_download_link`, soft-delete artifacts, and irreversibly seal sessions. |

The plugin may list all registered tools regardless of your grant. If a call
exceeds the granted tier, Artifacta returns `insufficient_scope` and names the
required scope. To broaden access, reauthorize:

```bash theme={null}
codex mcp logout artifacta
codex mcp login artifacta
```

Choose **Destroy** only when the workflow needs public share links, deletion,
or irreversible session sealing.

<Note>
  `get_artifact_download_url` is read-scoped and returns a one-hour presigned URL
  for direct retrieval. It is not a stable public share link.
  `create_download_link` creates the stable `dl.artifacta.io/lnk_…` URL and
  requires `artifacts:destroy`.
</Note>

The OAuth grant survives plugin removal. Revoke it separately from
[app.artifacta.io](https://app.artifacta.io) if you no longer want the
connection authorized.

## Update

Refresh the marketplace, then start a new thread so Codex loads the updated
cached plugin:

```bash theme={null}
codex plugin marketplace upgrade artifacta
```

For a project-local marketplace, reinstall the plugin after refreshing its
marketplace definition.

## Uninstall

```bash theme={null}
codex plugin remove artifacta@artifacta
```

This removes the plugin, its bundled MCP registration, skills, and hooks from
Codex. It does not delete any Artifacta artifacts or revoke the OAuth grant.

## What's next

* [Store session transcripts](/guides/transcripts#codex-plugin)
* [MCP overview](/mcp/overview)
* [MCP troubleshooting](/mcp/troubleshooting)
* [Claude Code plugin](/mcp/install/claude-code-plugin)