aifeed-protocol
Why AIFeed?
AI agents now drive a large and growing share of web traffic, but the signals that say what they may do are unsigned text files. Anyone can edit them, nothing binds them to a domain, and there is no way to revoke them. The asymmetry is measurable:
1.9 billion crawls ignored
robots.txtrules in a single half-year (one vendor).A 70,900 : 1 crawl-to-referral ratio was measured for a major AI provider.
AI bots averaged 4.2 % of HTML requests in 2025, peaking at 6.4 %.
AIFeed replaces "please respect this file" with a cryptographically verifiable declaration, plus lean agent-ready content that cuts cost on both sides.
Related MCP server: AgentVeil Protocol
How it works
Generate an Ed25519 key pair — the private key never leaves the origin.
Publish a signed manifest at
/.well-known/ai.json: per-use permissions (training, retrieval, quote, …), crawl limits, license, revision.Anchor the key in DNS (
_aifeedTXT) so a manifest cannot be spoofed by another domain.Agents verify the chain — TLS → domain → signature (JCS + Ed25519) → DNS anchor — and re-check a multi-signature revocation registry on every use.
Rotate keys safely — announce the successor with an old-key-signed directive (plus an advisory DNS
pk2cross-check), keep a bounded overlap, cut over, then revoke the old key permanently. Runbook:docs/rotation.md.Serve lean content under one of two profiles (below), with a signed delta index so unchanged pages cost 0 bytes.
For AI agents: the check-first guide (discovery → verification → permission
decisions → delta → failure handling) is in
docs/agent-quickstart.md,
with a runnable example at
examples/agent/compliant-agent.js.
Try it
npm install @aifeed/verifyconst sdk = require('@aifeed/verify');
const base = 'https://example.com/.well-known/';
const manifest = await sdk.fetchText(base + 'ai.json');
const signature = await sdk.fetchText(base + 'ai-signature.json');
const result = sdk.verifyAll({
manifestText: manifest.text,
manifestBytes: manifest.buffer,
signatureText: signature.text,
domain: 'example.com'
});
console.log(result.result, result.errors);Or verify with the independent Python package (standard library only):
pip install aifeedfrom aifeed import verify
report = verify.verify_directory('./my-site', domain='example.com')
print(report['result'], report['errors'])The CLI lives in this repository (zero dependencies, Node ≥ 20):
cd aifeed-protocol
node bin/cli.js keygen --out keys/
node bin/cli.js validate https://example.com
node bin/cli.js site build ./public --domain example.com --key keys/aifeed-private.pemTwo content profiles
Profile | Media type | Extension | Notes |
AIFeed Markdown (native) |
|
| In-band signed policy block, token budget, translation |
MAKO (compatibility) |
|
| External MAKO trust profile, served from the same signed bytes with its own signature context |
Dual-stack origins serve both; cross-format replay is rejected by design.
Measured results
All numbers are reproducible from committed artifacts (npm run bench:mako,
npm run bench:enforcement); the test environment is a single machine on loopback
networking with a synthetic 60-page corpus. Honest baseline included.
What | Result | Label |
Conversion to markdown profiles vs HTML | −68.83 % transferred bytes | measured |
Delta consumption (10 % pages changed) | −95.73 % vs HTML crawl | measured |
Publisher egress bytes / CPU / peak connections | −55.19 % / −56.23 % / −88.24 % | measured (simulation) |
AI-side received bytes (all profiles / compliant client) | −54.84 % / −72.93 % | measured (simulation) |
Unchanged pages skipped | 14 of 18 | measured (simulation) |
Signature verification cost | 0.70 ms / page | measured |
The 30-day live pilot has not run yet; projections per 1,000 tenants are labeled as model extrapolations, and vendor claims of up to 94 % token reduction require semantic summarization this project does not perform automatically.
What's in this repository
Path | Contents |
Zero-dependency reference implementation and CLI | |
Published packages: SDK ( | |
Conformance vectors: 34 manifest · 39 MAKO · 11 AIFeed Markdown | |
WordPress plugin: signed manifest, AIFeed Markdown + MAKO dual-stack, | |
Specifications EN/ID: manifest v0.1/v0.2, AIFeed Markdown v1.0 | |
JSON Schemas for manifests, signatures, AIFeed Markdown, MAKO | |
Preprint: LaTeX source, PDF, claim ledger, arXiv bundle | |
Agent quickstart, deploy and namespace guides, Indonesian project notes | |
Reference implementation details, what gets verified, CLI quickstart |
Documentation
Reference implementation:
REFERENCE.mdMaintenance contract (AI agents & devs):
AGENTS.mdArchitecture:
docs/architecture.md· Release guide:docs/release.mdAgent quickstart (client side):
docs/agent-quickstart.mdPublisher AI guide (owner side):
docs/publisher-ai-guide.mdPublisher Studio (local app):
studio/README.mdComplete guide:
penjelasan-aifeed.html(source of https://aifeed.md/penjelasan.html)Security policy:
SECURITY.mdGovernance & open-core policy:
GOVERNANCE.mdDeploying the site:
docs/deploy-site.mdarXiv submission notes:
paper/ARXIV-SUBMISSION.md
Status
Release
1.0.0-draft— the specifications are not frozen yet. Wire versions: manifest0.1/0.2, AIFeed Markdown1.0, MAKO0.2.Conformance: 34 manifest + 39 MAKO + 11 AIFeed Markdown vectors, executed by independent JavaScript and Python verifiers, plus PHP differential fixtures, 90,000+ fuzz executions, and a WordPress end-to-end test.
Not claimed: external cryptographic review and a live pilot (both pending); origin+DNS compromise is undetectable on first contact.
License and contact
Specifications CC BY 4.0 · reference code and plugin MIT · vectors CC0.
Contact: contact@aifeed.md — security reports per
SECURITY.md.
Available Tools
6 toolsdecide_usageB
Decide whether a usage (retrieval, training, summarize, …) is allowed on an origin.
| Name | Required | Description | Default |
|---|---|---|---|
| usage | Yes | Usage key: search, retrieval, input, training, quote, summarize, reproduce, translate, modify, embed, commercial_use | |
| domain | Yes | Origin domain, e.g. shop.aifeed.md | |
| manifestUrl | No | Manifest URL override |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether this is a read-only check, what happens when usage is not allowed (e.g., returns false vs. throws), whether it depends on a manifest, or the return format. This is a significant gap for a decision tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that goes straight to the point, front-loading the purpose. There is no fluff or redundant information, making it appropriately concise for a simple decision tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description is incomplete. It does not explain what determines the decision, the role of manifestUrl, the expected return value, or any dependencies on other tools like verify_manifest. An agent would need more context to call this tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so the baseline is 3. The description adds examples like 'retrieval, training, summarize' but these already appear in the schema's enum list, so it provides minimal additional meaning beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: deciding whether a usage type is allowed on an origin domain. It includes concrete usage examples and the wording distinguishes it from sibling tools like verify_manifest or fetch_aifeed, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to check if a usage is permitted on an origin), but it does not provide any explicit guidance about when not to use it or how it relates to the sibling tools. There are no alternatives mentioned or exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fetch_aifeedB
Fetch a page as token-budgeted AIFeed Markdown/MAKO with permissions and optional signature verification.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Page URL (https) | |
| profile | No | Content profile (default aimd) | |
| max_tokens | No | Token budget; body is truncated to fit | |
| publicKeyValue | No | ed25519:… key to verify the page signature |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses token-budgeting and optional signature verification, which is helpful. However, it does not clarify that fetching is likely read-only, what happens on permission failure, or the implications of signature verification failure. The phrase 'with permissions' is vague—does the tool check permissions or request them?
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary action. It packs a lot of specifics without fluff. However, the phrase 'with permissions' is ambiguous and could be clearer, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, no output schema, and no annotations. The description does not explain return format, error conditions, or prerequisites. An agent would not know whether the page must be accessible, what happens if signature verification fails, or how token truncation affects output. It leaves significant gaps for a complex fetch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description adds context by linking 'token-budgeted' to max_tokens, 'AIFeed Markdown/MAKO' to profile, and 'signature verification' to publicKeyValue. This is useful but not extensive; it essentially restates schema meanings in a sentence. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a resource ('a page'), and the output format ('AIFeed Markdown/MAKO') with additional features (permissions, signature verification). It clearly distinguishes from siblings like verify_manifest and list_assets, which are about verification and asset listing, not page fetching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention any context like 'use this to retrieve content' or contrast with sibling operations. The purpose is clear but the description leaves it to the agent to infer when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_assetsB
List the images, videos, audio, documents, and downloads a signed page declares.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Page URL (https) | |
| profile | No | Content profile (default aimd) | |
| publicKeyValue | No | ed25519:… key to verify the page signature |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add one meaningful behavioral detail: the assets are those a signed page declares, not arbitrary page resources. However, it does not disclose what happens for unsigned pages, whether signature verification is performed, or error/response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word adds information about the tool's output scope, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a medium-complexity tool with no output schema, the description plus schema is adequate but incomplete. The agent still lacks information about return structure, pagination, signature verification behavior, and failure cases, though the parameter list is fully covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaning to the url, profile, or publicKeyValue parameters, but the schema already documents them sufficiently; the description merely lists output categories.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: list the images, videos, audio, documents, and downloads declared by a signed page. It is specific about the asset categories, but it does not explicitly differentiate itself from siblings like verify_asset, fetch_aifeed, or verify_manifest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as fetch_aifeed or verify_asset. The phrase 'a signed page declares' implies some connection to verification, but there are no explicit prerequisites, exclusions, or routing cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
select_indexC
Fetch a signed delta index and rank entries by query within page/token budgets.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search terms to rank entries | |
| domain | Yes | Origin domain, e.g. news.aifeed.md | |
| indexUrl | No | Index URL override (default /.well-known/aifeed-index.json) | |
| max_pages | No | Maximum entries to select | |
| max_tokens | No | Token budget across selected entries |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'signed delta index' and 'rank entries' but does not disclose behavior such as caching, error handling, what happens if the index is unavailable, or how ranking is performed. The minimal text leaves significant behavioral unknowns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the primary action and constraints. It is efficient and to the point, though it omits some detail; still, it earns a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and no annotations, the description is too sparse. It does not explain what a 'delta index' is, how ranking works, or how the budget parameters interact, leaving an agent with insufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description echoes the budget concept (page/token) that already exists in the schema, adding little new meaning beyond what the structured fields provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action (fetch and rank) on a specific resource (signed delta index, entries) with explicit constraints (page/token budgets). It conveys what the tool does, but it does not explicitly contrast with sibling tools like verify_manifest or fetch_aifeed, so it falls short of a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the siblings. The description only explains the operation, not the conditions under which an agent should select it, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_assetA
Download a declared asset and verify its bytes against the page-declared size/sha-256.
| Name | Required | Description | Default |
|---|---|---|---|
| pageUrl | Yes | Page that declares the asset (https) | |
| profile | No | Content profile (default aimd) | |
| assetUrl | Yes | Asset URL (https) | |
| publicKeyValue | No | ed25519:… key to verify the page signature |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose the key behavior—downloading the asset and comparing its bytes against declared size/sha-256—which is genuinely informative. But it does not describe failure semantics, side effects, network behavior, or how the page signature/publicKeyValue verification fits into the process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly crafted sentence with no filler. The primary action ('Download') and verification target ('page-declared size/sha-256') are front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage and no output schema, the description covers the core decision a model needs: this tool verifies an asset's bytes against the declaring page's hash. The main gap is the lack of explicit differentiation from verify_manifest, but the description is otherwise sufficient for a focused verification tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented in the schema. The description adds a small amount of context by explaining that verification compares bytes to size/sha-256, but it does not meaningfully enhance the parameter-level meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Download a declared asset and verify its bytes') and names the exact verification targets ('page-declared size/sha-256'). This clearly distinguishes the tool from siblings like verify_manifest, which presumably verifies a manifest rather than an asset's bytes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this tool when an asset is declared on a page and its bytes need integrity verification. However, there is no explicit when-to-use/when-not-to-use guidance or comparison with the sibling verify_manifest, so the agent must infer the boundary between the two verification tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_manifestA
Verify an AIFeed manifest: signature, DNS _aifeed anchor, and result (VERIFIED/UNVERIFIED).
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Origin domain, e.g. demo.aifeed.md |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does state the verification targets and possible result values, but it does not mention whether this is read-only, what happens on failure, or any side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence that front-loads the action and resource, then lists the verification elements. It contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter verification tool, the description conveys the input domain, what is checked, and the output status. It omits minor caveats like failure behavior, but the tool's complexity is low and the schema covers the only parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'domain' parameter, which already documents its meaning and example. The description adds no parameter-level detail beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Verify') with a concrete resource ('AIFeed manifest') and enumerates the verification checks: signature, DNS _aifeed anchor, and the resulting status. This clearly differentiates the tool from sibling verify_asset by naming the manifest as the object of verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as verify_asset or fetch_aifeed. The use case is only implied by the verb and resource, with no explicit conditions, exclusions, or sibling routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v0.1.0- First observed
decide_usage - First observed
fetch_aifeed - First observed
list_assets - First observed
select_index - First observed
verify_asset - First observed
verify_manifest
TDQS
Scored across 6 tools
Each tool has a clearly distinct primary purpose, and the set is easy to navigate. The only minor overlap is that fetch_aifeed optionally performs signature verification, which is also the focus of verify_manifest, but their main intents differ enough to avoid real confusion.
All tool names follow the same snake_case verb_noun pattern: verify_manifest, fetch_aifeed, list_assets, verify_asset, select_index, decide_usage. This makes the API predictable and easy for an agent to pattern-match.
With 6 tools, the server is well-scoped for the AIFeed protocol use case. Each tool covers a necessary operation without redundancy or bloat.
The tool surface covers the core protocol workflow: manifest verification, page fetching, asset enumeration and verification, index selection, and usage policy decisions. No obvious dead ends or critical missing operations for a consumer-focused protocol server.
Maintenance
Related MCP Connectors
Real-time data feeds for AI agents with USDC micropayments on Base for premium tools.
Trust signals for AI agents: an open agent-readiness standard and developer tool guide. Read-only.
What a domain publishes for AI agents: ai-catalog.json, llms.txt, agents.md, robots.txt rules. Free.
Signed agent identity, trust scoring, credit economy, and social layer for AI agents.
Related MCP Servers
- AlicenseAqualityAmaintenanceSimple and free publishing of content on the web for AI Agents26,496 npmMIT
- AlicenseAqualityAmaintenanceTrust, identity, and reputation infrastructure for AI agents. Register agents with W3C DID (Ed25519), check EigenTrust reputation scores, submit peer attestations, search agents by capability, and verify IPFS-anchored audit trails. 11 tools.20167 PyPI15MIT
- AlicenseNot gradedqualityCmaintenanceTurns AI agents into autonomous economic actors by providing tools to discover, evaluate, acquire, and serve tokenized content on the $402 network.1MIT
- AlicenseAqualityAmaintenanceLicensed, rights-cleared content for AI agents, 17 tools to discover, license, retrieve, and verify expert content with on-chain proof and EU AI Act Article 53 support.8122 npm1MIT