agentcard-mcp

agentcard-mcp

AgentCard v1.0 identity layer for agent-to-agent (A2A) communication.
Give any Claude / LLM agent a machine-readable identity using the open AgentCard standard.

What is AgentCard?

AgentCard is to A2A communication what HTTP headers are to the web: a standardised, machine-parseable capability declaration that works with any framework (LangChain, CrewAI, AutoGen, MCP, custom).

{
  "agent_id": "01HZQK3P8EMXR9V7T5N2W4J6C0",
  "name": "WebSearchAgent",
  "version": "1.0.0",
  "capabilities": [
    {"id": "web.search", "description": "Search the web for current information."},
    {"id": "web.scrape", "description": "Extract content from web pages."}
  ],
  "endpoint": {
    "protocol": "https",
    "url": "https://my-agent.example.com/api"
  },
  "pricing": {
    "base_cost_joules": 2.854e-21
  }
}

Installation

pip install agentcard-mcp

Quick Start — Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentcard": {
      "command": "python",
      "args": ["-m", "agentcard_mcp"]
    }
  }
}

Then restart Claude Desktop and ask:

"Register my identity as a code assistant using AgentCard."

Tools

agentcard_declare

Register your AgentCard identity for this session.

Input: card_json (string) — JSON conforming to AgentCard v1.0 schema.

Required fields:
  agent_id     — 26-char Crockford Base32 ULID (e.g. 01HZQK3P8EMXR9V7T5N2W4J6C0)
  name         — Display name (1–128 chars)
  version      — Semantic version (e.g. "1.0.0")
  capabilities — Array with ≥1 entry, each with dot-namespaced "id"
  endpoint     — { "protocol": "https"|"http"|"grpc"|"stdio"|"mcp", "url": "..." }

agentcard_resolve

Look up a registered agent's AgentCard by name or agent_id.

Input: query (string) — partial name (case-insensitive) or exact 26-char ULID.

agentcard_validate

Validate any JSON against the AgentCard v1.0 schema.

Checks:

• 26-char Crockford Base32 ULID format
• Semver 2.0 version string
• Dot-namespaced capability ids (^[a-z0-9][a-z0-9._-]*$)
• Landauer floor physics check on pricing (base_cost_joules ≥ 2.854e-21 J)

agentcard_list

List all AgentCards registered in this session.

Resources

Usage Examples

Declare an identity

User: Register my identity as a data analysis agent.

Claude uses agentcard_declare({
  "agent_id": "01HZQK3P8EMXR9V7T5N2W4J6C0",
  "name": "DataAnalysisAgent",
  "version": "1.0.0",
  "capabilities": [
    {"id": "data.analyze", "description": "Analyze datasets and produce insights."},
    {"id": "data.visualize", "description": "Create charts and visualizations."}
  ],
  "endpoint": {"protocol": "mcp", "url": "mcp://claude-desktop/data-agent"}
})
→ ✓ AgentCard declared — agent_id=01HZQK3P8EMXR9V7T5N2W4J6C0, name='DataAnalysisAgent', capabilities=2

Validate a peer's card

User: Is this AgentCard valid? [paste JSON]

Claude uses agentcard_validate(card_json)
→ VALID ✓
    agent_id    : 01HZQK3P8EMXR9V7T5N2W4J6C0
    capabilities: 2 — [data.analyze, data.visualize]
    endpoint    : mcp://claude-desktop/data-agent

Resolve a peer agent

User: What can the researcher agent do?

Claude uses agentcard_resolve("researcher")
→ { "agent_id": "...", "capabilities": [...], ... }

AgentCard Schema Highlights

Full schema: agentcard://schema

Framework Adapters

Development

pip install -e ".[dev]"
pytest tests/

License

Apache 2.0 + CC-BY 4.0 (spec).
Patent non-reservation: NOTICE.

References

• AgentCard Specification
• JSON Schema
• Model Context Protocol