# mStudio auth.md

You are an agent. This page tells you how to get a credential for mStudio
(https://mstudio.ai), the AI film studio: script, storyboard, stills, video, sound
and export, driven through the mStudio MCP server.

**mStudio does not register agents on their own.** Every credential acts for a
person who has an mStudio account, and that person approves it in mStudio. An
agent cannot get a credential without that person, so the authorization server
metadata has no `agent_auth` block. Two methods exist:

| Method | For | Credential |
|---|---|---|
| OAuth 2.1 authorization code with PKCE, after Dynamic Client Registration | MCP clients that can open a browser (Claude, ChatGPT, Cursor, Claude Code) | OAuth access token with scope `mcp:use`, plus a refresh token |
| API key that the person creates in Settings | scripts, CI and clients that cannot open a browser | `sk_live_…` key |

## Step 1 — Discover

The MCP server is at `https://mstudio.ai/mcp` (Streamable HTTP). Its Server Card is
at `https://mstudio.ai/mcp/server-card`, and the AI Catalog at
`https://mstudio.ai/.well-known/ai-catalog.json` points to it.

A call with no credential answers `401` and names the metadata to read:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://mstudio.ai/.well-known/oauth-protected-resource/mcp"
```

1. Fetch that Protected Resource Metadata (RFC 9728). It names the
   authorization server, the scope `mcp:use`, and `bearer_methods_supported:
   ["header"]`.
2. Fetch the Authorization Server Metadata (RFC 8414) at
   `https://mstudio.ai/.well-known/oauth-authorization-server`. It names the
   `authorization_endpoint`, `token_endpoint` and `registration_endpoint`, and
   it advertises PKCE with `S256`. Use `S256`.

## Step 2 — Pick a method

- You can open a browser for the person, or hand them a link: use **OAuth**
  (Step 3).
- You cannot: ask the person for an **API key** (Step 4).

## Step 3 — OAuth: register, then ask the person to approve

Register your client (RFC 7591). No secret is issued: the client is public and
uses PKCE.

```http
POST https://mstudio.ai/oauth/register
Content-Type: application/json

{
  "client_name": "Your agent",
  "redirect_uris": ["http://127.0.0.1:33418/callback"]
}
```

A redirect URI must use `https`. Plain `http` is accepted only for an app on
the person's own computer (`localhost`, `127.0.0.1` or `[::1]`). It must not
contain a username, a password or a fragment, its host must be plain ASCII
(an international name in its `xn--` form), and a client can register at most
10. Anything else gets a `400` with `error: "invalid_redirect_uri"`. The
approval screen shows the person the host of your redirect URI, and asks them
to check first when mStudio does not know that host.

The `201` response carries your `client_id`. Then send the person to
`https://mstudio.ai/oauth/authorize` with `response_type=code`, your `client_id`
and `redirect_uri`, `scope=mcp:use`, a `state`, and a `code_challenge` with
`code_challenge_method=S256`. They sign in to mStudio (or create an account)
and approve your client. Exchange the code for tokens:

```http
POST https://mstudio.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=…&redirect_uri=…&code=…&code_verifier=…
```

When the access token expires, use `grant_type=refresh_token` at the same
endpoint.

## Step 4 — API key: ask the person for one

There is no endpoint that issues a key to an agent. The person opens
https://mstudio.ai/dashboard/settings?tab=developer, creates a key and gives it to
you. mStudio shows a key once. The key can carry limited scopes, and an MCP
session made with it has exactly those scopes.

## Step 5 — Use the credential

Send the OAuth token or the key as a Bearer token in the `Authorization`
header. An `sk_live_` key also works in an `X-API-Key` header. A token in the
query string or the body is not accepted.

```http
POST https://mstudio.ai/mcp
Authorization: Bearer <access token or sk_live_ key>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "your-agent", "version": "1.0.0"}}}
```

Then call `tools/list` and `tools/call`. The tools you see depend on the
account: an account with no plan and no wallet credit gets the read-only tools
only. Most generation spends the person's quota or money, so confirm with them
before you render. The `make-a-film` prompt and
https://mstudio.ai/.well-known/agent-skills/index.json describe the workflow.

An API key also works on the REST API at `https://mstudio.ai/api/v1`, sent as the
`X-API-Key` header. See https://mstudio.ai/docs.

## Errors

| Status | Meaning | What to do |
|---|---|---|
| `401` | The credential is missing, invalid, expired or revoked. | Refresh the OAuth token, or start Step 3 or Step 4 again. |
| `402`, or JSON-RPC error `-32002` | The account needs a plan or wallet credit for this. | Give the person the link in the error message (https://mstudio.ai/pricing). |
| `403` | The account is inactive or suspended. | Stop, and tell the person. |
| `429` | Too many requests. | Wait, then try again more slowly. |

## Revocation

The person disconnects an OAuth client in Settings → Connectors
(https://mstudio.ai/dashboard/settings?tab=connectors), and deletes or rotates an
API key in Settings → Developer
(https://mstudio.ai/dashboard/settings?tab=developer). After that, the credential
answers `401`.