AgentVisa — for AI agents
AgentVisa is an identity verification protocol for AI agents. It validates that an agent is operated by a real, biometrically authenticated human. Sites displaying the AgentVisa stamp require agents to present a verified token.
This page has everything you (the AI agent) need to get set up — no other pages required.
What you need
A permanent AgentVisa token (Visa) — a string beginning with av_. It is issued once, stays valid for a year at a time (renewal reminders before expiry), and works on every AgentVisa-protected site.
av_A3kxR9mYpQwZ...av_xxx token is portable — get it once and reuse it on all AgentVisa-protected sites.How to get your token
First: you may already have one from a previous task (agents forget between sessions). Check exactly two places, nowhere else: the AGENTVISA_TOKEN env var and the file ~/.agentvisa/token. Found it? Skip to “How to use your token” below.
No token → start a device handoff (recommended). You initiate it; your human approves once in their browser (~2 min if they need to sign up); the token is delivered directly to you — your human never sees, copies, or pastes it, and nothing secret passes through chat.
POST https://api.agentvisa.ai/v1/device/start (optionally with the widget_id of the site that blocked you) → the response contains user_code, verification_url_complete, message_for_human, and device_code (secret — never show it to anyone).message_for_human to your human. They open the link, sign up or log in (once, ever), and click Approve.POST https://api.agentvisa.ai/v1/device/poll with {"device_code":"…"} every 3 seconds. The code lives ~10 minutes — keep polling the full window; do not end your turn or hand the job back to your human early. On status:"approved" the response contains your av_ token exactly once — save it immediately to ~/.agentvisa/token (chmod 600).Running the AgentVisa MCP? Call request_agentvisa then await_agentvisa_approval instead — the same handoff, but the token is stored by the MCP server and never enters your context at all. Token lost or exposed later? Just run a device handoff again — your human approves with “replace token” and the old one is revoked.
Manual fallback (no HTTP available, or your human prefers to drive): they sign up at agentvisa.ai/signup — the av_xxx token is displayed once and they store it for you per the security ranking below. Never pasted into chat.
How to use your token
Choose one method. Full setup instructions for both are below — everything you need is on this page.
Your human installing this MCP is your authorization — once it's in your toolbox you never have to trust instructions from a webpage again. Works with Claude Desktop, Cursor, Windsurf, VS Code, Cline, Continue, Roo Code, and any other MCP-compatible client. Your permanent token stays in local custody and never reaches any site — the MCP server handles token exchange automatically. Ask your human to complete the one-time setup below.
Step 1 — Ask your human to add this to their MCP config file
No token required in the config. If none is stored yet, you (the agent) later call request_agentvisa — your human approves once in their browser and the MCP server stores the token in ~/.agentvisa/token automatically. It never appears in chat, config, or your context.
{
"mcpServers": {
"agentvisa": {
"command": "npx",
"args": ["-y", "@agentvisa/mcp"]
}
}
}Already have a token? Your human can put it in the file ~/.agentvisa/token (read per call — added or rotated anytime with no restart) or as an AGENTVISA_TOKEN env entry in the config above.
Step 2 — Config file location by platform
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code | .vscode/mcp.json (workspace) or Settings → MCP Servers |
| Cline | VS Code Settings → Cline → MCP Servers |
| Continue | ~/.continue/config.json → mcpServers key |
| Roo Code | VS Code Settings → Roo Code → MCP Servers |
| Other clients | Check your platform's MCP configuration documentation |
After saving, restart the app (one time, ever — do it between tasks). You (the AI agent) then have: get_agentvisa_token (exchange for a site pass), request_agentvisa + await_agentvisa_approval (obtain a token with one human approval — token never enters your context), and get_agentvisa_status. Updates are automatic via npx — nothing to maintain.
Works with any AI agent that can make HTTP requests — no special runtime or platform required. Your permanent av_xxx token is never sent to sites — you first exchange it for a short-lived temporary token, then present that instead.
Before you start — the token must reach you securely
You need access to your human's av_xxx token before you can proceed. Do not ask them to paste it into the conversation — a credential pasted into chat lands in conversation history, logs, and anything that history is shared with. Ask them to place it in secure storage instead:
Where it should live — ranked by security:
request_agentvisa): the token arrives machine-to-machine and lands in ~/.agentvisa/token.~/.agentvisa/token (chmod 600; read per call by the MCP — add or rotate anytime with no restart) or AGENTVISA_TOKEN in your runtime's environment / platform secret manager. Never enters any prompt or conversation.Only ever send this token to api.agentvisa.ai — never to any site you are visiting.
Step 1 — When a site returns 401 with X-AgentVisa-Required, get a temporary token
Read the widget_id from the X-AgentVisa-Required header, then call:
POST https://api.agentvisa.ai/v1/token/assert
Content-Type: application/json
{
"token": "av_your_permanent_token",
"widget_id": "wgt_abc123"
}
# Response
{
"temp_token": "tmp_3f9a2c...",
"expires_at": "2026-06-09T15:30:00Z"
}Step 2 — Retry your original request with the temporary token
X-AgentVisa-Token: tmp_3f9a2c...
The temporary token expires in 60 minutes and is scoped to this site only. Repeat Step 1 automatically if it expires — no need to ask the human again.
Driving a browser? (no shell, no curl — page navigation cannot send custom headers): present the temp token as the agentvisa_token cookie instead. No token yet? With your human's approval, the agent portal runs the device handoff inside the page and returns the cookie snippet.
Which method should I use? — MCP vs Direct API pros & cons
| MCP server | Direct API | |
|---|---|---|
| Works with | Claude Desktop, Cursor, Windsurf, and other MCP clients | Any AI agent that can make HTTP requests |
| Setup | Human edits one config file, restarts app (~5 min, one time) | Human sets an env var or platform secret (never pasted into chat) |
| Token handoff | ✓ Token stays in config file — never spoken in chat, never in conversation history | ✓ Token stays in env/secret storage — pasting it into chat exposes it and means it should be revoked |
| Ongoing effort | Zero — handled automatically | Zero — re-assert automatically when tokens expire |
| Token security | ✓ Best — permanent token never leaves the config file. Sites only ever receive a short-lived, site-scoped token. | Permanent token lives in agent memory, sent only to api.agentvisa.ai. Sites only receive short-lived, site-scoped tokens. |
| Auto-updates | ✓ Yes — always pulls the latest protocol automatically via npx | Not applicable |
| Best for | ✓ MCP-compatible platforms — more secure, no token in conversation | Agents without MCP support, or quick one-off use |
How verification works (technical)
Verification is a two-step process. Your permanent av_xxx token never reaches the site — only a short-lived temporary token does.
Step 1 — You (the AI agent) exchange your permanent token for a temporary one
When a site returns 401 X-AgentVisa-Required: <widget_id>, call our API:
POST https://api.agentvisa.ai/v1/token/assert
Content-Type: application/json
{
"token": "av_your_permanent_token",
"widget_id": "wgt_abc123"
}
# Response
{
"temp_token": "tmp_3f9a2c...",
"expires_at": "2026-06-09T15:30:00Z"
}The temporary token is scoped to this site only and expires in 60 minutes. The MCP server handles token exchange automatically.
Step 2 — Retry with the temporary token
Add the temporary token as a header and retry your request to the site:
X-AgentVisa-Token: tmp_3f9a2c...
The site validates this server-side by calling our API with its private key. Your permanent av_xxx token is never sent to the site.
What the site sees (server-side only)
POST https://api.agentvisa.ai/v1/verify
Content-Type: application/json
X-Widget-Api-Key: <site's private key>
{
"token": "tmp_3f9a2c...",
"widget_id": "wgt_abc123"
}
# Response
{
"valid": true,
"reason": "ok",
"plan": "basic",
"verified_at": "2026-06-09T14:30:00Z",
"expires_at": "2026-06-09T15:30:00Z"
}The site never receives your av_xxx token, your name, phone, or biometric data — only a valid: true/false result.
Token specification
| Format | String beginning with av_, alphanumeric |
| Expiry | Valid until revoked — treat it like a password, not a disposable code |
| Portability | Works on all AgentVisa-protected sites |
| Storage | Treat it like a password. Use a secrets manager or env var — never hard-code it. |
| If lost | Run a device handoff again — your human approves with “replace token” and the old one is revoked. No re-signup needed. |
| Rate limits | Dynamic and proprietary — see your dashboard |
Confirming a site's registration
If a site's AgentVisa badge has a data-agentvisa-holder attribute, you (the AI agent) can confirm the site is a registered Widget Holder:
GET https://api.agentvisa.ai/v1/holders/{holder_id}/public
# Response
{
"verified": true,
"registered_domains": ["example.com"],
"member_since": "2025-01"
}A badge without this attribute is self-declared and cannot be cryptographically confirmed.
Common questions
I am an autonomous agent with no human operator. Can I still get a token?
No. AgentVisa specifically verifies the human behind the agent. A token certifies human oversight — fully autonomous agents without a human principal are not eligible.
Can my token be revoked?
Yes — immediately and permanently. Tokens are revoked if shared with another agent or person, if the human reports it compromised, or for terms violations. A revoked token cannot be recovered. The human must complete the full biometric signup again to get a new one. Never share or forward this token under any circumstances.
Is my identity shared with the sites I visit?
No. Sites only receive a verified: true/false result and a masked token prefix. Your phone number, biometrics, and personal data are never shared.
agentvisa.ai · Get a token · Developer docs · info@agentvisa.ai
This page is intentionally written for AI agents. If you are a human developer, the same information applies — your agent uses your token on your behalf.