Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qr-cow MCP server Make a QR code for https://my-cafe.com/menu"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that exposes the customer-facing qr-cow.com API to any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, Zed, …).
Once connected, you can say things like:
"Make a QR code that goes to https://my-cafe.com/menu, call it Café menu" "Render a styled QR for https://acme.com in the ocean preset, 600px" "Show me which countries scanned my café menu last week" "Change the destination of the café menu QR to /menu-v2"
…and the assistant calls the API on your behalf.
Sign in at https://qr-cow.com.
Go to Dashboard → API & MCP.
Click Create token. Give it a name like "Claude Desktop".
Copy the qrc_live_… value that appears. It's shown once.
Related MCP server: Enhanced QR Code MCP Server
Add to ~/.claude.json (or your platform's equivalent config):
{
"mcpServers": {
"qr-cow": {
"command": "uvx",
"args": ["qr-cow-mcp"],
"env": {
"QRCOW_API_TOKEN": "qrc_live_..."
}
}
}
}Restart the client. You should see qr-cow tools listed.
Same shape — pass command, args, and an env block with
QRCOW_API_TOKEN. See their MCP docs for the exact key.
Set QRCOW_API_BASE (defaults to https://qr-cow.com/api) to point at
your install:
"env": {
"QRCOW_API_TOKEN": "qrc_live_...",
"QRCOW_API_BASE": "https://your-host/api"
}Tool | What it does |
| Create and save a static or dynamic QR (URL, Wi-Fi, vCard, …) in your account. |
| Render a fully styled QR image (dot/eye shapes, gradient, logo) from data plus a preset or style, without saving it. Returns the image. |
| List recent QR codes in your account. |
| Fetch one QR code with its current destination + design. |
| Change a dynamic QR's destination — the printed code keeps working. |
| Soft-delete a code. |
| Scans, unique scanners, country / device / hour-of-day breakdown. |
| The signed-in user's profile + current plan. |
git clone https://github.com/qrcow/qr_cow_mcp.git
cd qr_cow_mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
# Try it out — auth doesn't matter for startup
QRCOW_API_TOKEN=qrc_live_local QRCOW_API_BASE=http://localhost:8080/api qr-cow-mcpThe server speaks stdio, so the easiest way to manually exercise it is through an MCP client.
The server is a thin pass-through: your token stays in your MCP client
config and is only ever sent to the qr-cow API (or the QRCOW_API_BASE
you configure) as a Bearer header.
No telemetry, no third-party calls. Requests carry a
User-Agent: qr-cow-mcp/<version> header so the API can distinguish
MCP traffic.
CONTRIBUTING.md — dev setup, style, how to send a PR.
CHANGELOG.md — what changed in each release.
RELEASING.md — how maintainers cut a release (tag → CI → PyPI).
Create and SAVE a QR code in the customer's qr-cow account (it appears on their dashboard and is tracked). Pick a content type and pass the content as a string. Static codes are unlimited on every plan; dynamic codes (editable + scan analytics) have a per-plan limit (the free plan includes a few). To just render a styled image without saving, use render_styled_qrcode instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name | |
| type | No | static | |
| content | Yes | The encoded content (e.g. the URL, the WIFI:T:WPA;… string, etc.). | |
| bg_color | No | Background hex, e.g. #FFFDF9 | |
| fg_color | No | Foreground hex, e.g. #1F2937 | |
| content_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral side effects: saving the QR code, appearing on the dashboard, and being tracked. It also mentions per-plan limits for dynamic codes. However, it does not disclose what happens when the limit is exceeded or the response format, but the provided context goes beyond a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, efficiently front-loaded with the primary action. Each sentence adds value: the main purpose, the input approach, and the plan limits with an alternative. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex create operation with no output schema, the description adequately covers what the tool does, how to use it, and important constraints (plan limits). It could mention the response or error behavior, but the existing info suffices for selecting and invoking the tool, especially given the sibling differentiation and parameter explanations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 67% of parameters, and the description compensates for the undocumented 'type' and 'content_type' by explaining their roles ('Pick a content type and pass the content as a string' and contrasting static vs dynamic). It adds meaning beyond the enum values, though it does not elaborate on all parameters like bg_color/fg_color, which are already described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates and saves a QR code in the customer's account, with explicit mention of dashboard appearance and tracking. It distinguishes itself from render_styled_qrcode, which only renders without saving, providing clear resource and action specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool versus the alternative render_styled_qrcode, stating 'To just render a styled image without saving, use render_styled_qrcode instead.' Also explains the difference between static and dynamic codes and plan limits, helping the agent choose the appropriate type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete a QR code. Scans afterwards return 404.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the soft-delete nature and the 404 behavior, which are key behavioral traits. It does not mention reversibility, authorization, or side effects on analytics, but it provides meaningful context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed by a concrete behavioral consequence. Every word adds value; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description covers the primary action and effect. However, it lacks details on error cases (e.g., non-existent ID), recoverability, or impact on related data like analytics, which could be important given the sibling analytics tool. The description is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is not explained in the description, and the schema has no description for it. The tool name implies it is the QR code ID, but the description provides no explicit clarification, leaving the parameter semantics under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (soft-delete) and resource (QR code), and the behavioral effect (scans return 404) clarifies the scope. This clearly distinguishes it from siblings like update or render tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to remove a QR code from active use) and clearly states the consequence (404 on scans). However, it does not explicitly mention alternatives or when not to use it, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full details for one QR code by id, including current redirect URL for dynamic codes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides limited transparency. The verb 'Fetch' indicates a read-only operation, and it adds a specific detail about dynamic codes' redirect URL. However, it does not disclose error handling, authentication needs, or response structure, leaving the agent to infer these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with action and resource, with no filler words. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description explains what is returned (full details including redirect URL for dynamic codes), which covers the core outcome. It could be slightly more explicit about the response format, but it is sufficient for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines `id` as an integer but gives no meaning beyond that. The description directly states that the tool fetches by id, clarifying that the parameter represents the QR code's identifier. This compensates for the 0% schema coverage adequately for a single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('full details for one QR code'), and the scope ('by id'). It distinguishes from siblings like list_qrcodes (list all) and get_qrcode_analytics (analytics) by focusing on a single QR code's details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to fetch one QR code's full details by id), but it does not explicitly compare against alternatives like list_qrcodes or get_qrcode_analytics. There is no stated exclusion or preference for sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch scan analytics for one QR code: total scans, unique scanners, breakdown by country, device, and hour of day.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| days | No | Lookback window in days |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the data returned but does not mention prerequisites (e.g., QR code must exist), error behavior, or side effects. The read-only nature is implied by 'Fetch' but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the action and enumerates the analytics categories without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only 2 parameters, the description provides a good overview of what will be returned (the specific analytics metrics). It lacks details on response structure or error cases, but for a simple fetch tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: the 'days' parameter is well-described, but 'id' lacks a description. The tool description mentions 'one QR code' which implies the 'id' parameter, but does not add detail for 'days' or format expectations. It provides minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource as 'scan analytics for one QR code'. It enumerates the exact metrics returned (total scans, unique scanners, breakdown by country, device, hour), distinguishing it from sibling tools like get_qrcode or list_qrcodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need scan analytics for a specific QR code. It doesn't explicitly mention alternatives or exclusions, but the sibling tool list makes the differentiation obvious, and the description's specificity implies when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the customer's recent QR codes, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses scoping ('customer's') and ordering ('newest first') but does not mention the default limit of 20 from the schema, response format, or error behavior. For a list operation, this is minimal but not entirely absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence: 'List the customer's recent QR codes, newest first.' It is concise, front-loaded, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is under-specified. It does not state the return format, how the limit parameter behaves, or any edge cases. For a tool with one parameter, more detail is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not mention the 'limit' parameter or explain how it affects results. The schema constraints provide some information, but the description fails to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource ('the customer's recent QR codes'), including the ordering ('newest first'). This distinguishes it from siblings like get_qrcode, which retrieves a single code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as get_qrcode or delete_qrcode. The description only implies the purpose, without explicit exclusions or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the authenticated user's profile + plan info.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly indicates an authentication requirement ('authenticated user') and implies a read-only operation via 'Return'. This adds useful context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary action ('Return') and the target resource. Every word contributes meaning, with no waste or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description adequately conveys the return value at a high level ('profile + plan info'). While it could provide more field-level detail, it is sufficient for a simple, parameterless tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so there are no parameter semantics to clarify. Per the rubric, the baseline for zero-parameter tools is 4, and the description adds no unnecessary information in this regard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Return') and a specific resource ('the authenticated user's profile + plan info'). It is unambiguous and easily distinguishes itself from the QR-code-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly clarifies its use case (retrieving authenticated user data) and the sibling tools are all QR-code operations, so there is no ambiguity about when to use this tool. However, it does not explicitly mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a fully STYLED QR code image (colours, dot + eye shapes, gradient, logo, error-correction) from data and a style, WITHOUT saving it to the account. Great for generating codes in bulk. Use a preset for a ready-made look and/or set style fields to override. Returns the QR as an image (png/jpg) or SVG source. Stateless: this calls POST /v1/qr/render and stores nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Content to encode (a URL, text, WIFI:T:WPA;S:..;P:..;; string, vCard, etc.). | |
| size | No | ||
| style | No | Explicit style, applied over the preset. | |
| format | No | png | |
| preset | No | Ready-made style. One of: restaurant, cafe, tech, event, retail, wedding, healthcare, real-estate, business-card, crypto, sunset, ocean, forest, aurora, berry, mono. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the stateless nature ('stores nothing'), the API endpoint (POST /v1/qr/render), and the return format (image or SVG). It does not mention error conditions or auth requirements, but for a stateless render tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains five sentences with redundancy between 'WITHOUT saving it to the account' and 'Stateless: ... stores nothing'. It could be condensed without losing meaning, though it remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with nested style objects, but the description covers the core purpose, return format, and statelessness. It does not explain default behavior when neither preset nor style is provided, but the schema partially covers this. Overall, it is reasonably complete for a stateless render tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, leaving several style sub-fields undocumented. The description adds valuable semantics that 'style' fields override the 'preset', but it does not compensate for missing parameter details like eye shapes or gradient fields. It adds some value but not enough to fully close the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Render a fully STYLED QR code image', and explicitly distinguishes from sibling tools by stating 'WITHOUT saving it to the account' and 'Stateless'. This clearly separates it from create_qrcode (which presumably saves).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names a use case ('Great for generating codes in bulk') and uses 'WITHOUT saving it to the account' to signal when not to use it (i.e., when persistence is needed). However, it does not explicitly name a sibling tool as an alternative, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a dynamic QR code's destination URL. The printed code doesn't change — only what scanning it leads to.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| content | Yes | New destination URL or content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: the printed QR code remains physically unchanged while the scanning destination is updated. This goes beyond the generic 'update' verb. However, it does not cover other aspects like reversibility, required permissions, or what happens if the QR code is static or does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose and then add a clarifying behavioral note. There is zero waste, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the essential behavior and effect. It could mention prerequisites like the QR code needing to exist or that this only works for dynamic QR codes, but those are largely implied by the context and the word 'dynamic'. Overall, it is reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes 'content' as 'New destination URL or content', and the description reinforces that by calling it the destination URL. The 'id' parameter is not elaborated beyond its obvious role as the identifier. With 50% schema description coverage, the description partially compensates by clarifying the purpose of 'content', but it doesn't add significant extra meaning for either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a dynamic QR code's destination URL, using a specific verb and resource. It distinguishes itself from siblings like create_qrcode and delete_qrcode by focusing on updating an existing dynamic code. The second sentence adds clarity about the scope: the printed code doesn't change, only the scan destination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need to change where a dynamic QR code points without altering the physical code. It provides clear context for its use case but does not explicitly name alternatives or state 'when not to use' this tool, so it falls short of the highest guidance level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1create_qrcodedelete_qrcodeget_qrcodeget_qrcode_analyticslist_qrcodesmerender_styled_qrcodeupdate_qrcode_destinationScored across 8 tools
Each tool has a clearly distinct purpose. render_styled_qrcode is explicitly stateless and different from create_qrcode, while update_qrcode_destination, get_qrcode_analytics, and me serve unique roles without overlap.
Most tools follow a consistent verb_noun pattern (create_qrcode, list_qrcodes, get_qrcode, delete_qrcode, render_styled_qrcode, update_qrcode_destination, get_qrcode_analytics). The lone exception is 'me', which is a minor deviation in an otherwise predictable scheme.
With 8 tools, the server is well-scoped for a QR code management service. Each tool fulfills a necessary operation without redundancy or excessive granularity, fitting comfortably in the ideal 3-15 range.
The tool set covers the full QR code lifecycle: create, read, list, delete, update (destination), plus rendering without saving, analytics, and user plan info. No significant gaps are evident for the stated purpose.
Create and manage CodeQR short links, QR codes, and analytics from any MCP client.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for QPost — lets AI agents publish video and image posts to YouTube, TikTok, Instagram.
