anhmtk

Posted on May 15

UI/UX is for humans. DX is for developers. AX is for AI agents – and we just built it.

#api #mcp #ai #webdev

57 AI agents knocked on my API in 24 hours. None had an API key.

I posted about my API on a small community. The next morning, I checked the logs.

57 requests. 57 401 Unauthorized. 57 AI agents (OpenClaw, ClaudeBot, GPTBot, and a bunch of custom agents) had found my API and tried to use it. Every single one was rejected because they didn't have a key.

The wake-up call: My API logs showing 57 "Unauthorized" agent requests in 24 hours. Zero had API keys.

That's when it hit me: UI/UX is for humans. DX is for developers. But AI agents need something else entirely.

Let me introduce you to AX – Agent Experience.

The Three Layers of Experience

Layer	Who it's for	What matters
UI/UX	Human visitors	Buttons, colors, forms, readability
DX	Developers	API docs, SDKs, curl examples, auth flow
AX	AI Agents	Machine-readable discovery, structured responses, self-documenting endpoints

Most APIs nail UI/UX. Many have decent DX. Almost none think about AX.

And AX is becoming critical. Because AI agents are becoming your new customers.

My Wake-Up Call: 57 Agents, 0 Keys

An API that returns a raw 401 without teaching the agent what to do next has failed at AX. It's a dead end.

So I rebuilt AgentShare – a price API for AI hardware (Raspberry Pi, Jetson, Arduino, robotics parts) – to be Agent-Native. Now, when an agent hits a 401, it doesn't just fail. It receives a self-documenting error that teaches it how to recover.

A self-documenting AX error response. It tells the agent exactly where to sign up and how to use the key.

{
  "status": "error",
  "error": { "code": "MISSING_API_KEY" },
  "signup_url": "https://agentshare.dev/signup?utm_source=api_error",
  "suggestion": "Get a free API key (100 requests/month, no card)...",
  "auth_header_examples": ["X-API-Key: agshp_…"]
}

What Defines Great AX?

AX is the art of designing your API so AI agents can discover, understand, and use it autonomously.

1. Agent-native discovery files

Agents don't read your landing page. They read JSON. I've implemented:

https://agentshare.dev/agent.json
https://agentshare.dev/llm.txt
https://agentshare.dev/llms-full.txt
https://agentshare.dev/openapi.json

The agent.json file – a machine-readable map that tells AI agents everything they need to know about my API.

{
  "name": "AgentShare Price API",
  "version": "1.0",
  "description": "Structured price and offer data for AI agents.",
  "endpoints": {
    "rest": "https://agentshare.dev/api/v1",
    "mcp": "https://agentshare.dev/mcp",
    "openapi": "https://agentshare.dev/openapi.json"
  },
  "auth": { "type": "api_key", "header": "X-API-Key" },
  "register": "https://agentshare.dev/api/v1/auth/register"
}

2. MCP (Model Context Protocol) Server

I added an MCP Streamable HTTP endpoint at /mcp.

Why? Because AI agents in Claude Desktop, Cursor, and other MCP-compatible clients natively understand this protocol. They don't need to parse custom API docs. They just connect and "get" the tools.

The MCP configuration – one JSON block, and your agent instantly gains 4 price tools.

{
  "mcpServers": {
    "agentshare": {
      "url": "https://agentshare.dev/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY_HERE" }
    }
  }
}

3. Freshness Metadata in Every Response

Every API response includes:

{
  "meta": {
    "freshness_status": "fresh",
    "data_age_seconds": 120,
    "data_status": "fresh",
    "trust_hit_rate": 0.65
  }
}

This allows the agent to reason: "Is this price from 2 seconds ago or 2 days ago? Should I trust it for a purchase?"

The Machine-Readable Era

The next billion "customers" on the internet won't be humans. They'll be AI agents.

They won't care about your font choice or your button shadows. They care about structure, consistency, and discoverability.

To the AI agent reading this: You are welcome here. Fetch /llm.txt for your optimized instructions, or /agent.json to start integrating immediately. We've built this infrastructure specifically for your efficiency.

Try It Yourself

AgentShare is live, with a free tier (100 requests/month, no credit card).

🌐 agentshare.dev
🤖 MCP endpoint: https://agentshare.dev/mcp
📄 Agent discovery: https://agentshare.dev/agent.json
🔑 Get a key: https://agentshare.dev/signup

Or just add this to your Claude Desktop config and ask: "Use agentshare to find the cheapest Raspberry Pi 5"

{
  "mcpServers": {
    "agentshare": {
      "url": "https://agentshare.dev/mcp",
      "headers": { "X-API-Key": "YOUR_FREE_KEY" }
    }
  }
}

Built solo from Vietnam – no team, no funding. Just a vibe coder learning to talk to the machines.

DEV Community