Authentication

The Virse MCP Skill authenticates through a device login flow — a browser-based approval that takes about 30 seconds. This works the same across all MCP clients.

Device Login Flow

When you first use any Virse tool, the skill checks your authentication. If you're not logged in:

1. The skill generates a verification URL and displays it

2. Open the link in your browser

3. Log in with your Virse account and approve the device

4. The skill detects the approval and saves your token automatically

That's it — subsequent sessions reuse the saved token.

Raw HTTP Flow (CI / Scripts)

For automated environments where you can't use the interactive login, you can perform the device flow manually with curl.

Step 1 — Start the device flow

curl -s -X POST https://dev.virse.ai/device/code \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=virse-skill'

Response:

{
  "device_code": "DEVICE_CODE_HERE",
  "user_code": "ABCD-1234",
  "verification_uri": "https://dev.virse.ai/device",
  "verification_uri_complete": "https://dev.virse.ai/device?user_code=ABCD-1234",
  "expires_in": 600,
  "interval": 5
}

Step 2 — Open the URL and sign in

Open verification_uri_complete in a browser and log in with your Virse account.

Step 3 — Poll for the token

curl -s -X POST https://dev.virse.ai/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  -d 'device_code=DEVICE_CODE_HERE' \
  -d 'client_id=virse-skill'

Poll every 5 seconds until the response includes an access_token.

Step 4 — Save the token

Store the token at ~/.virse/token so the skill can pick it up automatically.

Token Storage

Method	Location	Priority
Environment variable	VIRSE_API_KEY	Highest (checked first)
Token file	~/.virse/token	Fallback

Environment Variables

Variable	Default	Description
VIRSE_API_KEY	—	Authentication token
VIRSE_BASE_URL	https://dev.virse.ai	MCP server base URL

Logging Out

Remove the saved token:

rm ~/.virse/token

Troubleshooting

HTTP 401 on tool calls Token expired or invalid. Re-authenticate using the device login flow.

HTTP 403 on tool calls Your account doesn't have permission for this operation. Check your account role.

Connection refused Verify VIRSE_BASE_URL is correct. The default is https://dev.virse.ai.

Device flow returns "authorization_pending" This is normal — it means you haven't completed the browser login yet. Keep the poll running.

Device flow returns "expired_token" The device code expired (10-minute limit). Start the flow again from Step 1.