MCP server
The hosted Model Context Protocol server that lets AI assistants work with your EZQR workspace.
EZQR hosts a Model Context Protocol server, so AI assistants such as Claude, ChatGPT, Claude Code and Cursor can create QR codes, change destinations and read analytics on your behalf. For setup steps in each app, see AI assistants.
Endpoint
https://mcp.ez-qr.com/mcpThe server uses the Streamable HTTP transport. It speaks protocol version 2026-07-28 and also serves clients on 2025-11-25, 2025-06-18 and 2025-03-26. It's stateless, so there are no sessions to keep alive.
MCP access is part of the Max plan.
Authorization
There are two ways to connect.
Sign in with OAuth (recommended)
Point your client at the endpoint. On the first request it gets 401 with a WWW-Authenticate header that links to the protected resource metadata, finds the authorization server and opens a consent screen where you pick what the app can do.
| Detail | Value |
|---|---|
| Protected resource metadata | https://mcp.ez-qr.com/.well-known/oauth-protected-resource/mcp |
| Authorization server | https://ez-qr.com |
| Authorization server metadata | https://ez-qr.com/.well-known/oauth-authorization-server |
| Grant types | authorization_code with PKCE (S256), refresh_token |
| Client registration | Client ID Metadata Documents, or Dynamic Client Registration at /api/oauth/register |
| Token audience | Tokens are bound to https://mcp.ez-qr.com/mcp with the resource parameter |
Access tokens last one hour. With offline_access, clients get a refresh token that rotates on every use and lasts 30 days. Each person connects as themselves, and can disconnect an app at any time in Settings → AI connections.
Workspace MCP key
For apps that can't sign in, a workspace owner or admin can generate one MCP key for the workspace in Settings → AI connections. Use it either in the URL or as a bearer token:
https://mcp.ez-qr.com/mcp/ezqr_mcp_…Authorization: Bearer ezqr_mcp_…The key only works with the MCP server, not the REST API. It has its own permissions, and actions made with it are recorded under the person who generated it. Rotating the key replaces it straight away.
Anyone with the key URL can use it. Keep it out of shared documents and repositories, and rotate it if it leaks.
Permissions
Each tool needs a permission (OAuth scope). Clients only see the tools their permissions allow.
| Scope | Allows |
|---|---|
qr:read | See QR codes, destinations and their status |
qr:write | Create QR codes and change where dynamic codes point |
analytics:read | See scan analytics |
leads:read | See leads and contacts |
cards:read | See digital business cards |
offline_access | Stay connected with a refresh token |
Tools
| Tool | Scope | What it does |
|---|---|---|
get_workspace | — | Shows the workspace, role and granted permissions |
list_qr_codes | qr:read | Lists QR codes with destination, scan link, status and scans |
get_qr_code | qr:read | Gets one QR code, including schedule and dashboard link |
create_qr_code | qr:write | Creates a dynamic or static QR code for a URL or other content |
update_qr_code | qr:write | Renames, repoints or pauses a QR code |
get_qr_analytics | analytics:read | Human scans, visitors and breakdowns for a code or the workspace |
list_leads | leads:read | The newest leads, with answers, filterable by form, card or tag |
list_cards | cards:read | Business cards with links and view, save and exchange counts |
Every tool returns structured content with an output schema where one is declared, plus the same data as text for older clients. Tools carry annotations so clients can tell read-only tools from ones that change data. update_qr_code is marked destructive because it changes where printed codes send people.
Errors
| Status | When |
|---|---|
401 | No token, or the token or key is invalid, expired or revoked |
403 | The plan doesn't include AI connections, or the request came from a disallowed browser origin |
429 | More than 120 requests a minute from one connection |
Problems inside a tool, such as an unknown QR code id, come back as a tool result with isError: true, so the assistant can read the message and try again.
Try it
Use the MCP Inspector to explore the server:
npx @modelcontextprotocol/inspectorEnter https://mcp.ez-qr.com/mcp as the server URL and sign in when asked.