Create and validate machine-readable agent cards to make small businesses discoverable by AI assistants.
Also known as flowboxx/agent-card-starter, agent-card-starter
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 679
- Latest version
- 0.2.2
- Last commit
- Nov 6, 2026
- License
- MIT
What is Agent Card Starter MCP?
Agent Card Starter creates and validate machine-readable agent cards to make small businesses discoverable by AI assistants.
Summary generated from the project's README
About Agent Card Starter MCP server
This toolkit helps small business owners create machine-readable files that allow AI assistants to discover their services. It provides a way to generate and verify agent cards following the A2A v1.0 standard and MCP server cards based on the SEP-2127 proposal. By using these files, a business can communicate its skills and supported interfaces to automated agents.
Developers use the agent-card command-line tool to initialize new cards with specific business details like name, description, and website. The package includes a validator to check for required fields and sanity rules offline without needing an account or internet connection. It is a local Python-based solution that relies only on the standard library, making it easy to integrate into existing workflows.
The starter kit also includes a minimal MCP example server that communicates over stdio. This allows users to learn how to implement tools like leistungen and anfrage_anlegen. Once the files are validated, they are intended to be hosted at a specific path on the business domain to ensure visibility.
What you can do with it
- 1Generate a new business cardA developer can quickly create a starting JSON file for a business by providing its name and description.
- 2Validate agent card complianceUsers can run a strict validation check on their machine-readable files to ensure they meet necessary standards.
- 3Test an MCP server implementationYou can run a minimal example server over stdio to see how tools appear to an AI client.
Written from the project's README. Every use case is checked against a quote from it.
How to install Agent Card Starter MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Agent Card Starter MCP in Claude Code
$ claude mcp add agent-card-starter -- uvx agent-card-starterInstall Agent Card Starter MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agent-card-starter": {
"command": "uvx",
"args": [
"agent-card-starter"
]
}
}
}Install Agent Card Starter MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agent-card-starter": {
"type": "stdio",
"command": "uvx",
"args": [
"agent-card-starter"
]
}
}
}Install Agent Card Starter MCP in VS Code CLI
$ code --add-mcp '{"name":"agent-card-starter","type":"stdio","command":"uvx","args":["agent-card-starter"]}'Install Agent Card Starter MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agent-card-starter": {
"command": "uvx",
"args": [
"agent-card-starter"
]
}
}
}Install Agent Card Starter MCP in Codex
$ codex mcp add agent-card-starter -- uvx agent-card-starterInstall Agent Card Starter MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agent-card-starter] command = "uvx" args = ["agent-card-starter"]
Install Agent Card Starter MCP in Gemini CLI
$ gemini mcp add -s user agent-card-starter uvx -- agent-card-starterInstall Agent Card Starter MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agent-card-starter": {
"command": "uvx",
"args": [
"agent-card-starter"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableflowboxx/agent-card-starter is public and reachablegithub.com/flowboxx/agent-card-starter ↗Pass
- Package names this repository as its sourceagent-card-starter names flowboxx/agent-card-starter as sourcepypi.org/project/agent-card-starter/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/flowboxx/agent-card-starter ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agent-card-starterPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagent-card-starter
Write and check the machine-readable card that makes a small business readable for AI assistants. Its WordPress sibling, Open Door for AI Assistants, goes one step further: an AI assistant will be able to leave an inquiry for the business, and the business gets it as an e-mail (inquiry service coming soon).
In 60 seconds: AI assistants read a small JSON file to learn what your business does. This tool writes that file for you and checks it. Offline, no account, no dependencies.
pip install agent-card-starter
agent-card init --name "Muster Roofing Ltd" --description "Roofer in Musterstadt, repairs and new roofs." --website https://www.example.com --skill "Flat roof sealing"
agent-card validate .well-known/agent-card.json --strict
Upload the file to https://<your-domain>/.well-known/agent-card.json and you are readable. Nothing here guarantees that an assistant will mention you.
In 60 Sekunden: KI-Assistenten lesen eine kleine Datei, um zu erfahren, was Ihr Betrieb macht. Dieses Werkzeug schreibt die Datei und prüft sie. Ohne Netz, ohne Konto, ohne Fremdpakete. Befehle siehe oben, die Datei kommt nach https://<Ihre-Domain>/.well-known/agent-card.json.
Starter kit to make a small business readable and reachable for AI assistants: an A2A agent card, an MCP server card, a minimal MCP example server and a validator. Standard library only, Python 3.9+, MIT licensed.
Starter-Set, damit ein kleiner Betrieb für KI-Assistenten lesbar und erreichbar wird: Agentenkarte (A2A), Server-Karte (MCP), ein minimaler MCP-Beispielserver und ein Prüfskript. Nur Python-Standardbibliothek, ab Python 3.9, MIT-Lizenz.
Maintained by flowboxx, an agency that builds AI doors for businesses. Gepflegt von flowboxx, einer Agentur, die KI-Türen für Betriebe baut.
English
What is in here
| Path | What it is |
|---|---|
examples/well-known/agent-card.json |
A2A agent card for a fictional "Beispiel Dachdecker GmbH" |
examples/well-known/agent.json |
Byte-identical copy for older readers |
examples/agent-card.annotated.jsonc |
Same card with comments (documentation only) |
examples/mcp-server-card.json |
MCP server card for the same business |
templates/ |
Blank-ish templates: server card and AI catalog |
server/mcp_server.py |
MCP example server over stdio: tools leistungen and anfrage_anlegen (stub) |
agent_card/ |
The agent-card command: init writes a first card, validate checks card, server card and catalog (offline) |
tools/validate_agent_card.py |
Same validator as a plain script |
tests/ |
pytest suite |
Quick start
agent-card init --name "Your Business" --description "What you do and where." --website https://www.example.com
agent-card validate .well-known/agent-card.json --strict
# from a clone, without installing:
python3 tools/validate_agent_card.py examples/well-known/agent-card.json
python3 tools/validate_agent_card.py examples/mcp-server-card.json --strict
printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | python3 server/mcp_server.py
python3 -m pip install pytest && python3 -m pytest -q
docker build -t agent-card-starter . && docker run -i --rm agent-card-starter # MCP over stdio
Use it for your business
- Copy
examples/well-known/agent-card.json, replace name, description, provider, skills. - List only services you really offer. One skill per service, stable ids.
- Keep prices, phone numbers and promises out of the card. A human answers those.
- Run the validator, publish the file at
https://<your-domain>/.well-known/agent-card.json. - Point
supportedInterfacesat an endpoint you really operate. The example server speaks MCP over stdio for learning. A public endpoint needs HTTP transport, rate limiting, spam protection and a privacy notice.anfrage_anlegenis a stub on purpose.
Notes on the standards
- The agent card follows the A2A v1.0 field names (
supportedInterfaces,skills,provider). - The server card follows the MCP Server Card proposal (SEP-2127). It is an extension and the schema may still change. Check the current schema before you publish.
- The validator checks required fields and a few sanity rules. It is not a full JSON Schema validation.
- Nothing here guarantees that an assistant will mention or recommend you.
Deutsch
Was drin ist
| Pfad | Inhalt |
|---|---|
examples/well-known/agent-card.json |
A2A-Agentenkarte für die fiktive "Beispiel Dachdecker GmbH" |
examples/well-known/agent.json |
Byte-gleiche Kopie für ältere Leser |
examples/agent-card.annotated.jsonc |
Dieselbe Karte mit Kommentaren (nur zur Erklärung) |
examples/mcp-server-card.json |
MCP-Server-Karte für denselben Betrieb |
templates/ |
Vorlagen: Server-Karte und KI-Katalog |
server/mcp_server.py |
MCP-Beispielserver über stdio: Werkzeuge leistungen und anfrage_anlegen (Stub) |
agent_card/ |
Der Befehl agent-card: init schreibt eine erste Karte, validate prüft Karte, Server-Karte und Katalog (ohne Netz) |
tools/validate_agent_card.py |
Dasselbe Prüfskript als einfache Datei |
tests/ |
pytest-Tests |
Schnellstart
agent-card init --name "Ihr Betrieb" --description "Was Sie tun und wo." --website https://www.example.com
agent-card validate .well-known/agent-card.json --strict
# aus einem Klon, ohne Installation:
python3 tools/validate_agent_card.py examples/well-known/agent-card.json
python3 tools/validate_agent_card.py examples/mcp-server-card.json --strict
printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | python3 server/mcp_server.py
python3 -m pip install pytest && python3 -m pytest -q
docker build -t agent-card-starter . && docker run -i --rm agent-card-starter # MCP over stdio
Für den eigenen Betrieb nutzen
examples/well-known/agent-card.jsonkopieren, Name, Beschreibung, Anbieter und Fähigkeiten ersetzen.- Nur Leistungen eintragen, die Sie wirklich anbieten. Eine Fähigkeit je Leistung, stabile Ids.
- Keine Preise, Telefonnummern oder Zusagen in die Karte. Das beantwortet ein Mensch.
- Prüfskript laufen lassen, Datei unter
https://<Ihre-Domain>/.well-known/agent-card.jsonablegen. supportedInterfacesauf einen Endpunkt zeigen lassen, den Sie wirklich betreiben. Der Beispielserver spricht MCP über stdio zum Lernen. Ein öffentlicher Endpunkt braucht HTTP, Mengenbegrenzung, Spam-Schutz und einen Datenschutzhinweis.anfrage_anlegenist absichtlich ein Stub und speichert nichts.
Hinweise zu den Standards
- Die Agentenkarte folgt den Feldnamen von A2A v1.0 (
supportedInterfaces,skills,provider). - Die Server-Karte folgt dem MCP-Vorschlag Server Card (SEP-2127). Das ist eine Erweiterung, das Schema kann sich noch ändern. Vor dem Veröffentlichen das aktuelle Schema prüfen.
- Das Prüfskript prüft Pflichtfelder und einige Plausibilitäten, keine vollständige JSON-Schema-Validierung.
- Nichts hier garantiert, dass ein Assistent Sie nennt oder empfiehlt.
Built with this? Tell us / Damit gebaut? Erzählen Sie es uns
If you published a card with this kit, show it in Discussions, Show and tell. We read every one. If you like, add the badge to your README:
Wenn Sie mit diesem Kit eine Karte veröffentlicht haben, zeigen Sie sie unter Discussions, Show and tell. Das Abzeichen für Ihre README:
[](https://github.com/flowboxx/agent-card-starter)
As is / Ohne Gewähr
This is a starting point, provided "as is" under the MIT license, without warranty of any kind. Standards around agent cards and server cards are young and change. Check the current specifications before you publish. Nothing here is legal advice, and nothing guarantees that an assistant will mention or recommend your business. Changes are listed in CHANGELOG.md, how to help is in CONTRIBUTING.md.
Dies ist ein Ausgangspunkt, bereitgestellt "wie besehen" unter der MIT-Lizenz, ohne Gewähr. Die Standards rund um Agentenkarten und Server-Karten sind jung und ändern sich. Prüfen Sie vor dem Veröffentlichen die aktuellen Spezifikationen. Nichts hier ist Rechtsberatung, und nichts garantiert, dass ein Assistent Ihren Betrieb nennt oder empfiehlt. Änderungen stehen in CHANGELOG.md, Mitmachen steht in CONTRIBUTING.md.
MIT License, see LICENSE. Questions and contributions welcome via issues. Fragen und Beiträge gern als Issue.
Built and maintained by flowboxx, Germany.
Agent Card Starter MCP questions
How do I add Agent Card Starter MCP to Claude Code?
Run claude mcp add agent-card-starter -- uvx agent-card-starter in your terminal. Add --scope user to make it available in every project.
How do I add Agent Card Starter MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does the tool do?
It allows you to write and check machine-readable cards that make a small business readable for AI assistants.
Does it require an internet connection or an account?
No, the tool works offline without requiring an account or external dependencies.
What standards does the agent card follow?
The agent card follows the A2A v1.0 field names including supportedInterfaces, skills, and provider.
Does using this tool guarantee my business will be recommended by AI?
No, the tool provides the files, but it does not guarantee that an assistant will mention or recommend you.