agent-seo

April 15, 2026 · View on GitHub

SEO for Agents — Score any AI agent endpoint on trust & capability metrics.

There are 56,000+ MCP servers. How do you know which ones are trustworthy before you use them? And if you're building one, how do you know it's discoverable?

Two use cases, one tool:

Before you USE an agent → Score it to check if it's trustworthy, well-documented, and maintained
Before you RELEASE an agent → Score yourself to find what's missing and improve discoverability

Quick Start

git clone https://github.com/manavaga/agent-seo.git
cd agent-seo
pip install -e .

# Score any agent
agent-seo score https://your-agent-url.com

# HTTP checks only (faster, skip MCP handshake)
agent-seo score https://your-agent-url.com --skip-mcp

Use as MCP Server (Claude, Cursor, ChatGPT)

Add agent-seo to your MCP config so AI assistants can score agents inline:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agent-seo": {
      "command": "python",
      "args": ["-m", "agent_seo.mcp_server"],
      "cwd": "/path/to/agent-seo"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "agent-seo": {
      "command": "python",
      "args": ["-m", "agent_seo.mcp_server"],
      "cwd": "/path/to/agent-seo"
    }
  }
}

Then ask your AI assistant: "Score the agent at https://mcp.context7.com" — it will call agent-seo and return the full trust score with fix recommendations.

Available MCP Tools

Tool	What It Does
`score_agent`	Score any agent URL — returns score, grade, category breakdown, fix recommendations
`compare_agents`	Compare two agents side by side — shows which is stronger in each category
`get_fix_recommendations`	Get prioritized fixes with expected point gains and code templates

Real Scores (v0.5)

Agent	Score	Grade	Tools	What It Does
GitMCP React	76/100	B	4	Serves React documentation via MCP
AWS Knowledge	74/100	B	6	AWS docs, APIs, code samples
Context7	73/100	B	2	Up-to-date library documentation
DeepWiki	64/100	C	3	AI-powered repo documentation
Jina AI	62/100	C	21	Web search and content extraction
CoinGecko	50/100	C	50	Crypto market data

All scores include 5/5 dimensions assessed with High confidence.

What It Checks

5 categories. 100 total points. Always scores all 5 dimensions.

Category	Max Pts	What It Measures
Schema & Interface Quality	25	Tool descriptions, parameter docs, types, safety annotations
Functional Reliability	25	MCP handshake, response latency, health endpoint, performance metrics
Developer Experience	20	API docs, llms.txt, discovery endpoints, GitHub repo quality
Ecosystem Signal	15	GitHub stars, forks, topics, brand recognition
Maintenance Health	15	Commit recency, license, issue health, active status

All 5 dimensions are always present. If GitHub data isn't found directly, the tool searches by server name, domain, and known brand database. No category is silently dropped.

Example Output

╭──────────────────────── agent-seo v0.5 ─────────────────────────╮
│ Agent SEO Trust Score: 73/100  Grade: B  (73%)                  │
│ Confidence: High (5 of 5 dimensions assessed)                   │
│ https://mcp.context7.com                                        │
╰─────────────────────────────────────────────────────────────────╯

SCHEMA & INTERFACE QUALITY  14/25  ✓ 2 tools, documented params
FUNCTIONAL RELIABILITY      12/25  ✓ MCP connected, 2 tools via handshake
DEVELOPER EXPERIENCE         5/20  ✓ Docs available
ECOSYSTEM SIGNAL            15/15  ✓ 52,384 stars, relevant topics
MAINTENANCE HEALTH          12/15  ✓ Active, MIT license, healthy issues

TOP FIXES (highest impact first):
  1. Tool descriptions quality (+7 pts)
     → Add detailed descriptions (50+ chars) to each tool
  2. Performance metrics endpoint (+6 pts)
     → Add GET /performance with success rates and accuracy
  3. Health endpoint (+4 pts)
     → Add GET /health returning status and uptime

Every failed check includes what to fix, how to fix it, and spec links.

How It Works

MCP Protocol Handshake

Connects to the agent via 8 common MCP paths (covering 99%+ of servers):

/mcp, /mcp/stream, /sse, /mcp/sse, /, /v1, /api/mcp, /api/llm/mcp
Auto-detects transport (Streamable HTTP or SSE)
Inspects tools/list for schema quality and safety annotations

GitHub Intelligence

Finds the GitHub repo using 5 strategies:

Direct link in agent card
Link found in HTTP endpoints
Known-brand subdomain lookup (20+ companies mapped)
MCP server name search via GitHub API
Domain name search as fallback

Supports GITHUB_TOKEN env var for authenticated API access (5000 req/hr vs 60).

HTTP Endpoint Checks

Probes well-known URLs for discovery, documentation, health, and performance data.

Deploy as Remote MCP Server

Host agent-seo so anyone can use it without installing:

# Local
uvicorn agent_seo.server:app --host 0.0.0.0 --port 8000

# Docker
docker build -t agent-seo .
docker run -p 8000:8000 agent-seo

# Railway (one-click deploy)
railway up

Once deployed, users just add the URL:

{"mcpServers": {"agent-seo": {"url": "https://your-deploy-url.com/mcp"}}}

The hosted version exposes all trust endpoints:

/health — uptime, scan count, error rate
/.well-known/agent.json — A2A Agent Card
/.well-known/mcp.json — MCP discovery
/performance — scoring service metrics
/docs — Swagger API documentation
/llms.txt — LLM-readable description

Options

# JSON output
agent-seo score URL --format json

# Save results
agent-seo score URL --save

# Compare multiple agents
agent-seo batch URL1 URL2 URL3

# CI/CD: fail if below threshold
agent-seo score URL --fail-below 60

# Skip MCP handshake (HTTP only, faster)
agent-seo score URL --skip-mcp