> ## 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.

# Connect Claude Code (Hosted)

> Connect Claude Code to Artifacta over the hosted MCP endpoint with OAuth — one command, a browser login, no package install and no API key to copy.

The **hosted MCP endpoint** is the recommended way to connect Claude Code to
Artifacta. You add one URL, log in through your browser once, and pick the
permissions on a consent screen — no npm/PyPI package, no local process, and no
`ak_live_` API key pasted into a config file.

```text theme={null}
https://mcp.artifacta.io/mcp
```

<Note>
  Hosted and local MCP expose the **same Artifacta tools** — this is a different
  connection method, not a different product. Prefer the local stdio package for
  CI, restricted networks, or when you want explicit control over credentials and
  process execution: see [Install in Claude Code (stdio)](/mcp/install/claude-code).
</Note>

## Prerequisites

* **Claude Code** installed (`claude --version`).
* **A free Artifacta account.** Sign up at
  [app.artifacta.io/signup](https://app.artifacta.io/signup) — you log in with
  this account during the OAuth step below.

Nothing else. There is no package to install and no API key to create for the
hosted path.

## Primary install — one command

Add the hosted server by URL. Claude Code registers itself with Artifacta
automatically (OAuth Dynamic Client Registration) and uses PKCE — **no client
id, no callback port, and no client secret to configure**:

```bash theme={null}
claude mcp add --transport http artifacta https://mcp.artifacta.io/mcp
```

That writes:

```json theme={null}
{
  "type": "http",
  "url": "https://mcp.artifacta.io/mcp"
}
```

<Note>
  Artifacta supports **OAuth 2.1 Dynamic Client Registration (RFC 7591)**, so
  Claude Code self-registers a one-time **public** client (PKCE, no secret) the
  first time it connects. You do not paste a `clientId` or pick a callback port —
  Claude Code chooses an ephemeral loopback port for the login redirect itself.
</Note>

### Alternative — fixed client (manual / pre-DCR fallback)

If your client does not support Dynamic Client Registration, or you want to pin
Artifacta's registered **public** OAuth client explicitly, use the `add-json`
form with the fixed `clientId` and `callbackPort`:

```bash theme={null}
claude mcp add-json artifacta '{
  "type": "http",
  "url": "https://mcp.artifacta.io/mcp",
  "oauth": {
    "clientId": "d685c6a7-5cb9-4612-ba2b-cab12e38d9e0",
    "callbackPort": 8080,
    "scopes": "openid"
  }
}' --scope local
```

Or the equivalent flags:

```bash theme={null}
claude mcp add --transport http \
  --client-id d685c6a7-5cb9-4612-ba2b-cab12e38d9e0 \
  --callback-port 8080 \
  artifacta https://mcp.artifacta.io/mcp
```

<Note>
  The `clientId` above is Artifacta's registered **public** OAuth client — a public
  identifier, safe to commit, with **no client secret**. Do **not** pass
  `--client-secret`; Artifacta uses PKCE. `scopes` is `openid` only — Artifacta
  tool permissions are chosen on the consent screen, not through the OAuth `scope`
  parameter (see [Permissions](#permissions)). Both the one-liner and this fixed
  form connect to the same endpoint and work in parallel.
</Note>

## Authenticate

Adding the server does not log you in — `claude mcp list` shows `artifacta` as
needing authentication until you complete the browser flow once.

<Steps>
  <Step title="Open Claude Code">
    Start a session in your project:

    ```bash theme={null}
    claude
    ```
  </Step>

  <Step title="Run /mcp">
    Type `/mcp` in the session, select **artifacta** from the list, and choose
    **Authenticate**.
  </Step>

  <Step title="Log in and consent">
    Claude Code opens your browser to Artifacta. Sign in with your account, then
    on the **consent screen** tick the permissions you want to grant this
    connection (see [Permissions](#permissions)) and click
    **Authorize**.
  </Step>

  <Step title="Done">
    After **Authorize**, the browser redirects to a local
    `http://localhost:<port>/callback` (or `127.0.0.1`) URL — this is the
    loopback listener Claude Code opened to receive the OAuth code, and a brief
    "you may close this tab" page or a momentary blank page is **expected**.
    Return to Claude Code; `/mcp` shows **artifacta** as connected and the
    granted tools appear in the session.
  </Step>
</Steps>

<Note>
  During **Authenticate**, Claude Code opens a one-shot loopback listener
  (`http://localhost:<port>/callback`) itself to receive the OAuth redirect —
  **you do not run a server**. With the one-liner, the port is chosen
  automatically; with the fixed-client `add-json` form, `callbackPort: 8080` pins
  it to match Artifacta's registered redirect URI.
</Note>

To re-authenticate (for example to change which permissions you granted), run
`claude mcp logout artifacta`, then `/mcp` → **artifacta** → **Authenticate**
again.

## Permissions

You choose Artifacta's permissions (read / write / destroy) on the **consent
screen** during
authentication — not through the OAuth `scope` parameter. Each tier is nested:
write includes read, and destroy includes write.

| Grant         | Authorized tools                                                                                                      | Adds                                                                          |
| ------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Read**      | **5** — `whoami`, `list_artifacts`, `get_artifact`, `get_artifact_download_url`, `list_sessions` (plus all resources) | Browse and download your own artifacts.                                       |
| **+ Write**   | **8**                                                                                                                 | `store_artifact`, `request_upload_url`, `complete_upload`                     |
| **+ Destroy** | **11**                                                                                                                | `create_download_link` (public share URLs), `delete_artifact`, `seal_session` |

The client may continue to list tools outside the granted tier. Artifacta
authorizes each call server-side; a denied call returns `insufficient_scope`
and names the required scope. Reauthenticate to broaden the grant.

<Warning>
  **Destroy** is elevated risk — it includes minting **public** share links,
  soft-deleting artifacts, and **irreversibly** sealing sessions. The consent
  screen marks it accordingly. Grant it only when your workflow needs those
  actions.
</Warning>

After connecting, confirm the surface with a smoke prompt:

> "What's my Artifacta plan?"

Claude Code calls the `whoami` tool (available at every permission tier) and
reports your tenant, plan, and usage.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Consent screen says “Unverified”">
    Expected. Artifacta does not pre-verify the application names that
    self-registering clients submit, so every OAuth consent screen shows an
    **Unverified** label and the redirect URI for you to check. Confirm the
    redirect URI is a local loopback address (`http://localhost:…` or
    `http://127.0.0.1:…`) before you **Authorize**.
  </Accordion>

  <Accordion title="“does not support dynamic client registration”">
    Your client could not self-register. Artifacta **does** support Dynamic
    Client Registration, but if your client or network blocks it, fall back to
    the fixed **public** client: use the
    [`add-json` / `--client-id` form](#alternative--fixed-client-manual--pre-dcr-fallback)
    with `clientId` `d685c6a7-5cb9-4612-ba2b-cab12e38d9e0`.
  </Accordion>

  <Accordion title="“unsupported scope artifacts:*”">
    The OAuth authorization request must use `"scopes": "openid"` only (the
    one-liner does this for you). Artifacta's tool permissions (read / write /
    destroy) come from the consent screen, **not** the OAuth `scope` parameter —
    requesting `artifacts:*` at authorize time is rejected by the authorization
    server. If you set `scopes` explicitly, set it to `openid` and re-run.
  </Accordion>

  <Accordion title="token error mentioning client_secret_basic">
    Artifacta is a **public** OAuth client and has no client secret. Remove any
    `--client-secret` flag or stored secret — authenticate with PKCE only.
  </Accordion>

  <Accordion title="A tool returns insufficient_scope">
    The tool is registered, but the current OAuth grant does not authorize the
    call. Run `claude mcp logout artifacta`, then `/mcp` → **artifacta** →
    **Authenticate** again and select the required tier. **Destroy** is required
    for public share links, soft deletion, and irreversible session sealing.
  </Accordion>
</AccordionGroup>

## Headless / CI (advanced)

For unattended agents and CI that cannot run an interactive browser login, the
hosted endpoint also accepts a raw `ak_live_` API key as a bearer token. This is
the **advanced / CI-only** path — interactive users should use OAuth above. See
the [stdio + API key install](/mcp/install/claude-code) and the hosted
`ak_live_` curl smoke in the
[`@artifacta-mcp/mcp` README](https://github.com/SagaPeak/artifacta-mcp).

## What's next

* **[Install in Claude Code (stdio)](/mcp/install/claude-code)** — the local
  package with an `ak_live_` API key, for CI, restricted networks, and explicit
  credential control.
* **[MCP overview](/mcp/overview)** — the full tool and resource surface, shared
  by hosted and local.