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:loginorscripts/device-auth.sh(see the agent plugin repo) instead of exportingFORMSPRING_TOKENby 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
- Client
POST /mcp/device/sessionwith{ "client": "cursor", "abilities": ["forms:read", ...] }. - Response includes
user_code,device_code,verification_uri_complete,expires_in, andinterval. - User opens
verification_uri_complete(or/mcp/device?user_code=XXXX-XXXX), signs in, and approves abilities. - Client polls
POST /mcp/device/tokenwith{ "device_code": "..." }untilstatusissuccessandaccess_tokenis 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:
./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.
