Pre-connection discoverability for MCP servers and web apps.
Agents can't find the tools they need until the door is opened. They can't open the door until they know which door to open.
This is the MCP discovery loop. There are tens of thousands of MCP servers. An agent has no way to evaluate which one is relevant to its task without connecting first. Connecting requires registration and credentials. But you don't register a server until you know it has what you need. The agent is blind until a human has already done the legwork.
Even when the right server is registered and the agent connects, it still has to guess. It calls tools/list, reads through every tool definition, picks one, and hopes. It hallucinates button IDs, calls the wrong tools, fails silently. The result is frustrated users, broken automations, and AI assistants that look incompetent — even when the underlying model is excellent.
llms.txt tells AI what your site is.
sitemap.xml tells crawlers what pages exist.
robots.txt tells bots where they can't go.
Nothing tells an AI agent which server to connect to, which tool to call, or how to actually do something inside your app — before it connects.
A blueprint.txt file at /.well-known/blueprint.txt on your web app.
One plain text file. No tooling required. Any developer can write one in under 10 minutes.
blueprint.txt is publicly readable — no auth, no registration, no connection required. An agent can fetch it and evaluate your server before knocking on the door. It reads the CAPABILITIES block and knows immediately: does this server have what I need? What's the MCP URL? What transport? What inputs does the tool expect?
The agent arrives informed, not speculative. It connects once, calls the right tool directly, and stops burning context on everything else.
For MCP specifically, this eliminates a protocol call entirely.
MCP has two calls: tools/list — which returns every tool the server exposes — and tools/call — which calls a specific tool by name. Without a blueprint, an agent calls tools/list first, reads through all N tool definitions, picks one, then calls it. With a blueprint, the agent already knows the tool name and exact parameters. It calls tools/call directly. tools/list never happens.
That's not just cheaper discovery. It's the removal of a round trip.
This is all you need to get started (Format A — small app, everything inline):
# BLUEPRINT: Habit Tracker
# Version: 3.1.2
# URL: https://yourhabittracker.app
## CAPABILITIES
## CAPABILITY: log-habit
description: Mark a habit as complete for today and update the user's streak.
input:
- name: habit-name
type: string
required: true
description: The name of the habit to mark complete.
output:
- type: confirmation
description: Habit logged. Streak count updated.
auth-required: true
scope: form-submit
### UI
steps:
1. ASSERT-AUTH
2. NAVIGATE /dashboard
3. WAIT [data-agent-id="habit-list"] (max: 10s)
4. CLICK [data-agent-id="habit-<<habit-name>>-complete"]
5. WAIT [data-agent-id="streak-updated"] (max: 5s)
6. VERIFY selector_exists [data-agent-id="streak-updated"]
## IDENTITY
name: Habit Tracker
description: Build and maintain daily habits. Log completions, track streaks, and stay accountable over time.
category: productivity
contact: support@yourhabittracker.app
## AUTH
provider: firebase
method: email
## ACCESS
last-resort: ui
That's a complete, working blueprint. An AI agent can read the CAPABILITIES block and log a habit without reading anything else.
Larger apps use Format B — an index in the CAPABILITIES block pointing to individual capability files. Agents fetch only the file they need. See SPEC.md for the full Format B syntax and the Imagcon example for a live reference implementation.
AI agents work reliably with your app.
Claude, ChatGPT Operator, Gemini — they are already attempting to automate tasks inside web apps, with or without your permission. Give them a map and they work correctly. Without one, they guess and your users blame your app.
Tools that consume blueprints can serve your app automatically.
A blueprint-ready app can be picked up by any tool that reads the standard — demo video generators, agent frameworks, onboarding tools — without you writing custom integrations for each one.
The barrier is low. The upside compounds.
A 20-line file written today makes your app more valuable to every AI agent and blueprint-aware tool that exists now and in the future.
Your blueprint keeps your app honest.
The same document agents use to navigate your app can verify that everything else you say about it stays accurate. Feed your blueprint to an AI alongside your homepage, FAQ, or feature descriptions and ask: does the app match what you're claiming? A blueprint kept current becomes a single source of truth for your entire public-facing representation — not just for agents, but for your own consistency.
If you have an MCP server, a blueprint solves the discovery problem.
There are tens of thousands of MCP servers. An agent connecting to all of them burns its entire context window on tool definitions before it reads a single user message. A blueprint lets an agent read one plain text file and know whether your server is relevant to the task, which tool to call, and what inputs it needs — before connecting. The agent arrives with intent, not speculatively. Blueprint Protocol treats MCP as the preferred access method: declare your server in ## MCP, map each capability to its tool name, and agents that support MCP will use it automatically over API or UI fallbacks.
Full spec: SPEC.md
Blueprint is designed for indie developers and small teams — not enterprise software. The two examples cover the full range:
| Example | What it shows |
|---|---|
| Habit Tracker | The floor — no API, no MCP, UI only. Any app can start here. |
| Demo Video Tool | The ceiling — MCP-first, blueprint consumer, async jobs. |
Most apps live somewhere in between. Start with the habit tracker pattern and add layers only when you have them.
Capabilities first, invocation second.
Declare what the app can do before describing how to invoke it. The capability contract stays stable even when the implementation changes.
Only declare what actually exists.
No API block unless there is a real endpoint. No MCP block unless there is a real server. A blueprint with false entries is worse than no blueprint — it causes silent failures.
data-agent-id, not CSS selectors.
UI steps use [data-agent-id="x"] — a dedicated attribute that won't conflict with styling or get renamed in a refactor. Add it to your HTML alongside the blueprint step that references it.
One action per step.
One CLICK, one INPUT, one NAVIGATE per line. No combining actions. This makes flows unambiguous for agents and clean for any tool that replays them.
WAIT after every async operation.
If the UI has a loading state, there must be a WAIT step. Agents and any tool that replays the flow need to know when to proceed.
I didn't build this as a software architect. I built it as a manufacturer who manages a business with 13 different apps, a shop floor full of wood cable reels, and a life that doesn't have room for broken AI automations.
In manufacturing, we use standardized pallets because if the notches don't line up, the forklift can't move the product. Blueprint Protocol is that standardized pallet for the AI era.
I'm a vibe coder — I use AI to build and deploy because I'd rather spend my time solving real-world friction than getting lost in complex code. I noticed that even the smartest AI agents hallucinate when they look at a website. They guess where to click, they fail, and they waste time.
This protocol exists to stop the guessing. It's a 10-minute text file designed for the person who wants their tools to work the first time, every time. No enterprise bloat, no complex servers — just a map so the agent can get the job done while you focus on your actual work.
In manufacturing we call this an SOP — a standard operating procedure. A document that tells anyone who needs to use a process exactly how to use it, step by step, without guessing. That's what blueprint.txt is. An SOP for AI agents.
I built this by thinking out loud with AI — Claude and Gemini were my collaborators throughout. Every decision in this spec came from real problems I hit in production, argued through with AI until the reasoning held up. The ideas are mine. The AI helped me articulate them, stress-test them, and write them down.
— Jill Mercer
Version: 3.1.2 — Draft
This is an open standard. Use it, fork it, extend it.
If you build something with it, open a PR to add your example.
Blueprint Protocol is an open standard. Licensed under MIT.
In April 2026, Blueprint Protocol was tested in production. StackApps — an indie app directory — implemented the three-surface discovery pattern (blueprint pointer in llms.txt, <link rel="blueprint"> in HTML <head>, and # Blueprint: as the first line of robots.txt). The assessment was run by StackLaunch, an autonomous AI content and SEO/AIEO assessment engine built on the same suite.
Of three crawlers assessed, Gemini detected, fetched, and positively referenced the blueprint.txt unprompted. Grok and Claude did not surface it. Gemini's assessment included:
"Your strategy of enforcing a 'machine-readable contract' via blueprint.txt is brilliant for AIEO."
"The AI-Readable Directory. Stop fighting Product Hunt for human eyeballs. Become the foundational API layer where AI agents and LLMs go to find, vet, and invoke lightweight indie tools via blueprint.txt."
Gemini's detection is significant given its direct connection to Google Search. The result suggests the three-surface pattern meaningfully increases fetch likelihood for reasoning models, though a single test is not conclusive. Further real-world data is needed.
See IMPLEMENTATION.md for the full discovery pattern used in the test.