# Spiral authentication (auth.md)

> How an AI agent authenticates with Spiral over MCP, and how a user's Spiral
> account is created. There is no API key to paste for the standard flow: the
> first connection opens a browser for the user to sign in and authorize access.

Spiral's MCP server is at `https://api.writewithspiral.com/mcp/` (Streamable HTTP). It is an OAuth 2.1
protected resource. Most clients handle the flow below automatically once you
add the server.

## OAuth on first connect (recommended)

1. **Discover.** The MCP client fetches the protected-resource metadata
   (RFC 9728) at `https://api.writewithspiral.com/.well-known/oauth-protected-resource`. It names the
   authorization server and the supported scopes (`profile`, `email`).
2. **Authorize.** The client opens a browser to the authorization server and the
   user signs in to Spiral and grants access (OAuth 2.1, PKCE). No secret is
   pasted into the terminal or the agent.
3. **Account creation is automatic.** If the user doesn't already have a Spiral
   account, authorizing creates one on the spot — there is no separate signup
   step. A personal workspace is set up for them.
4. **Call tools.** The client sends the issued access token as
   `Authorization: Bearer <token>` on every MCP request. Spiral resolves the
   token to the user and runs tools as them.

As an agent, you generally don't drive these steps yourself — your MCP client
does. Your job is to tell the user when it's their turn to sign in, then confirm
the tools are available once they have.

## Personal access token (headless / CI)

For clients that can't open a browser, a user can create a personal access token
in the Spiral app (Settings → API keys) and provide it to the client. Send it the
same way: `Authorization: Bearer spiral_sk_...`. Treat it as a secret; it can be
revoked from the same settings page.

## After authentication

- Setup and read tools work on any account, including a free one.
- The writing tools require a paid plan; see [pricing.md](https://writewithspiral.com/pricing.md).
- Per-client connection steps: [agents.md](https://writewithspiral.com/agents.md).
- Overview: [Spiral for agents](https://writewithspiral.com/agents).

## Contact
- Email: hi@writewithspiral.com