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

# Authentication

> How OAuth works with the Artificial Studio MCP server.

The MCP server uses **OAuth 2.1 with PKCE** — the same flow Claude Code and Cursor use for all their MCP integrations. You don't need an API key.

## The flow (first use)

<Steps>
  <Step title="Client requests a tool">
    Your AI client (Claude Code, Cursor, etc.) calls an MCP tool — say, `generate`.
  </Step>

  <Step title="Server returns 401">
    Without a valid Bearer token, the server returns `401 Unauthorized` with a `WWW-Authenticate` header pointing to the OAuth metadata.
  </Step>

  <Step title="Client opens browser">
    The client starts an OAuth flow: opens `https://app.artificialstudio.ai/connect` in your default browser with a PKCE challenge.
  </Step>

  <Step title="You sign in and approve">
    You sign in to Artificial Studio (if not already) and click **Authorize**. The browser redirects back to your AI client's localhost callback with an auth code.
  </Step>

  <Step title="Client exchanges for token">
    The client exchanges the code for a Bearer token and stores it locally. From here on, every MCP request includes `Authorization: Bearer <token>`.
  </Step>
</Steps>

## OAuth endpoints

The server exposes standard OAuth discovery metadata:

| Endpoint                                  | Purpose                                                     |
| ----------------------------------------- | ----------------------------------------------------------- |
| `/.well-known/oauth-protected-resource`   | Resource metadata referenced from 401 responses             |
| `/.well-known/oauth-authorization-server` | Authorization server metadata (endpoints, supported grants) |
| `/oauth/authorize`                        | Authorization endpoint (browser)                            |
| `/oauth/token`                            | Token endpoint (exchange code, refresh)                     |
| `/oauth/register`                         | Dynamic client registration (DCR)                           |

Supported grants:

* `authorization_code` (with PKCE — required)
* `refresh_token`

## Scopes

Current scopes granted:

* Read your account (credits, plan, profile)
* Read your generations
* Run generations (charges your credits like the dashboard)

## Token storage

Tokens are stored **by the client**, not by Artificial Studio:

* **Claude Code**: OS keychain / `~/.claude`
* **Cursor**: OS keychain
* **Claude Desktop** (via `mcp-remote`): `~/.mcp-auth/` directory

Revoking a token from our side is possible via [app.artificialstudio.ai/account](https://app.artificialstudio.ai/account) under **Connected apps** (coming soon).

## Redirect URIs

For native clients, the server's redirect URI whitelist accepts:

* `http://localhost:<port>/*`
* `http://127.0.0.1:<port>/*`

This is per [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252) — AI clients run a tiny local HTTP server during the OAuth dance to receive the code.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Browser doesn't open on first use">
    Some clients (especially in SSH / headless sessions) can't launch a browser. Copy the authorize URL from the client logs and open it manually on a machine where you're logged in — then paste the callback URL back into the client when prompted.
  </Accordion>

  <Accordion title="'invalid_token' after working for a while">
    Your access token expired and the refresh failed. Remove the stored token and re-authenticate:

    * **Claude Code**: `claude mcp remove artificial-studio && claude mcp add --transport http artificial-studio https://api.artificialstudio.ai/mcp`
    * **Cursor**: remove the entry from `mcp.json`, restart, re-add.
    * **Claude Desktop (mcp-remote)**: `rm -rf ~/.mcp-auth/` and restart.
  </Accordion>

  <Accordion title="'redirect_uri mismatch'">
    The port your client chose for the OAuth callback isn't accepted. Make sure you're on the latest version of your MCP client — old versions sometimes pick non-localhost URIs. If it persists, open a support ticket with the exact redirect\_uri from the error.
  </Accordion>

  <Accordion title="Multiple accounts">
    Each machine / profile stores one token. To switch accounts, remove the stored token (see above) and re-authenticate with the other account.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tool reference" icon="wrench" href="/mcp/tools">
    All 6 tools, their args, and responses.
  </Card>

  <Card title="Async & polling" icon="clock" href="/mcp/async-polling">
    How to handle long-running generations.
  </Card>
</CardGroup>