> ## 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)](https://docs.artifacta.io/mcp/install/claude-code.md).

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

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

## Authenticate

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

**1. Open Claude Code**

Start a session in your project:

```bash theme={null}
claude
```

**2. Run /mcp**

Type `/mcp` in the session, select **artifacta** from the list, and choose
**Authenticate**.

**3. 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**.

**4. 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.

> [!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.

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.

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

> [accordion] 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] “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] “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] 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] 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.

## 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](https://docs.artifacta.io/mcp/install/claude-code.md) 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)](https://docs.artifacta.io/mcp/install/claude-code.md)** — the local
  package with an `ak_live_` API key, for CI, restricted networks, and explicit
  credential control.
* **[MCP overview](https://docs.artifacta.io/mcp/overview.md)** — the full tool and resource surface, shared
  by hosted and local.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.