All docs

Device authorization for agents

Sign in from the browser to connect Cursor, Claude Code, and other MCP clients without copying tokens.

Updated . 3 min read.

Formspring supports an RFC 8628-style device authorization flow. Your agent plugin or CLI requests a short code, you approve the connection in the browser, and the client receives a scoped API token automatically.

When to use it

  • Cursor / Claude Code plugins - run /formspring:login or scripts/device-auth.sh (see the agent plugin repo) instead of exporting FORMSPRING_TOKEN by hand.
  • Any HTTP MCP client - use the same endpoints from a script if you prefer browser approval over pasting bearer tokens.

Manual token minting remains available on MCP setup and API tokens.

Flow

  1. Client POST /mcp/device/session with { "client": "cursor", "abilities": ["forms:read", ...] }.
  2. Response includes user_code, device_code, verification_uri_complete, expires_in, and interval.
  3. User opens verification_uri_complete (or /mcp/device?user_code=XXXX-XXXX), signs in, and approves abilities.
  4. Client polls POST /mcp/device/token with { "device_code": "..." } until status is success and access_token is present.

Poll statuses:

status Meaning
authorization_pending Waiting for browser approval
success Token issued (one-time; includes config_string for your client)
access_denied User denied in the browser
expired_token Code expired (default 15 minutes)

Approval before risky actions

A token issued by this flow asks you before it runs a risky tool (deleting, messaging people outside your workspace, billing, keys and secrets, access changes). Approve each call from the link the assistant shows. You can switch this off per token in API tokens. See Ask me before risky actions.

Discovery

OAuth metadata for automation:

  • Protected resource: GET /.well-known/oauth-protected-resource/mcp-server
  • Authorization server: GET /.well-known/oauth-authorization-server

Resource indicator

A client may send the optional resource field (RFC 8707) with the session request. It must be the MCP endpoint, https://formspring.io/mcp-server (a trailing slash is fine). Any other value is refused with 400 and "error": "invalid_target", so a token is never started for a server it will not be accepted by. Clients that do not send resource are unaffected.

Authorization-code flow

There is no authorization-code (browser redirect with PKCE) flow yet. Advertising an authorization_endpoint without dynamic client registration makes generic MCP clients try to register themselves at /register, which is the signup route, so the metadata deliberately lists only the device flow. Use the device flow above, or a token from API tokens. The resource check described above is the same RFC 8707 rule an authorization-code flow would apply.

Plugin CLI

From the formspring-ai repository:

bash
./scripts/device-auth.sh cursor
# or
FORMSPRING_DEVICE_CLIENT=claude-code ./scripts/device-auth.sh

The script prints export FORMSPRING_TOKEN=... when finished. Add that to your shell profile or plugin settings.

Security

  • Device codes are single-use and stored hashed.
  • Tokens are scoped to the abilities chosen at session start (or adjusted on the approval page).
  • Revoke access anytime from MCP setup or API tokens.