FindUtils Agent Discovery: APIs, MCP, and Markdown References

FindUtils publishes machine-readable entry points for its REST API, MCP server, and tool references. A compatible client can use these resources to discover schemas and connection details. Support depends on the client. Publishing an endpoint does not guarantee automatic connection or an AI citation.

The examples below show where to retrieve each resource. Check the current API catalog and MCP reference for available tools and connection instructions.

Discovery helps a client find the contract

A tool integration needs a service address, input schema, output expectations, and access rules. Discovery documents place those facts at predictable URLs.

A client must still support the document format and decide to use it. Search citations are a separate outcome. There is no basis for treating a server card or llms.txt file as a universal citation requirement.

Use the AI Agent Starter Guide for practice with coding agents. Use the API and MCP references for actual FindUtils service contracts.

Published discovery resources

1. RFC 8288 Link response headers on every page

The public header configuration advertises these resources. Check the response on the URL you plan to use:

link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"
link: </api/openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json;version=3.1"
link: </api>; rel="service-doc"; type="text/html"
link: </llms.txt>; rel="describedby"; type="text/plain"
link: </.well-known/agent-skills/index.json>; rel="https://agentskills.io/rels/skills-index"; type="application/json"
link: </.well-known/mcp/server-card.json>; rel="https://modelcontextprotocol.io/rels/server-card"; type="application/json"

Verify it:

curl -sI https://findutils.com/ | grep -i ^link

2. /.well-known/api-catalog (RFC 9727)

An application/linkset+json catalog that points clients at the listed services — REST API at api.findutils.com and MCP server at mcp.findutils.com — along with OpenAPI spec, human docs, and health endpoints.

curl -s https://findutils.com/.well-known/api-catalog | jq

3. /.well-known/mcp/server-card.json

The published server card describes the MCP endpoint. Client support for this descriptor is not universal. The following URL-based configuration is illustrative:

{
  "mcpServers": {
    "findutils": { "url": "https://mcp.findutils.com/" }
  }
}

Use the current MCP tool listing for identifiers and schemas. The catalog includes developer utilities for formats, text, and calculations.

4. /.well-known/agent-skills/index.json + SKILL.md files

A skills discovery index per the Agent Skills Discovery RFC v0.2.0, with three skills shipped:

• call-tool-api — how to invoke the REST endpoints
• call-mcp-server — how to initialize and call the MCP server
• browse-site — how to navigate FindUtils catalogs, sitemaps, and LLM-friendly references

Each skill is a SKILL.md file with a sha256 digest in the index so agents can verify integrity.

5. WebMCP via navigator.modelContext.provideContext()

The shared page layout conditionally registers three browser actions when the expected API exists:

• searchTools — open the tool listing with a keyword query
• openTool — open a listing search for the supplied slug
• callToolApi — construct candidate REST URLs; verify the identifier in the API catalog

Execution depends on browser support and the client's permission model. The action itself does not validate every constructed REST URL.

6. Markdown for Agents — Accept: text/markdown

Pages with a Markdown sibling support this request:

curl -H "Accept: text/markdown" https://findutils.com/calculate/gpa-calculator/

Response:

Content-Type: text/markdown; charset=utf-8
Vary: Accept
X-Markdown-Source: sibling-md

---
title: "GPA Calculator"
url: https://findutils.com/calculate/gpa-calculator
---

# GPA Calculator
...

The HTML response stays the default for browsers. Agents that prefer markdown get a clean, LLM-optimized version with no JS, no nav chrome.

7. Content Signals in robots.txt

The current public robots file includes this Content Signals directive:

Content-Signal: search=yes, ai-train=yes, ai-input=yes

This states the published policy. It does not grant a right to private data or prove that an AI service will cite the site.

8. Link elements in HTML head

Beyond the response headers, every page also renders HTML <link rel="alternate"> elements pointing at llms.txt and api/llms.txt — a belt-and-suspenders redundancy for agents that parse HTML but not headers.

9. llms.txt, llms-full.txt, and api/llms.txt

These were already shipped, but they're the foundation of the whole stack:

• https://findutils.com/llms.txt — site overview
• https://findutils.com/llms-full.txt — expanded tool references
• https://findutils.com/api/llms.txt — REST API reference

The agent discovery cheat sheet

Here's the full set of entry points an agent can hit:

What each discovery resource establishes

Inspect the current catalog and connection response before choosing a tool. Static discovery descriptions can become stale. An integration still needs authentication, input validation, error handling, and a successful test request.

How to connect a compatible client

MCP clients

Use the remote HTTP endpoint https://mcp.findutils.com/. Follow the connection instructions for your client and version. Some clients use a connector interface; others use a configuration file or an adapter.

This is an illustrative shape for a client that supports this URL-based configuration:

{
  "mcpServers": {
    "findutils": {
      "url": "https://mcp.findutils.com/"
    }
  }
}

It is not a universal Claude Desktop configuration. Use the current FindUtils MCP instructions before applying it. List the available tools after connection, then test a non-sensitive input.

Read the API catalog with Python

import httpx

r = httpx.get("https://findutils.com/.well-known/api-catalog").json()
for entry in r["linkset"]:
    print(entry["anchor"], "→", entry["service-desc"][0]["href"])

This example prints the descriptors in the current catalog shape. A production client also needs status checks, timeouts, and handling for missing fields or a changed response.

Retrieve a Markdown variant

Send Accept: text/markdown for a URL that has a Markdown sibling. Check the response Content-Type before parsing it as Markdown. The site can fall back to HTML where no sibling exists.

Optional browser actions

The browser integration checks for navigator.modelContext.provideContext before registration. It does nothing if that API is absent. Browser and agent support can change. Do not assume that every visitor has these actions available.

Verify the endpoint before relying on it

Retrieve the current descriptor and compare it with the service documentation. Check the transport, supported method, tool identifier, argument schema, and access limits.

Static discovery files can become stale. Treat a live tool listing and current service reference as stronger evidence than a tool count in an older article. Keep integration errors visible so a changed contract does not silently break a workflow.

Tools mentioned in this post

• AI Agent Starter Guide — Interactive playground for Claude Code, Copilot, Cursor, Gemini, Codex, Windsurf
• AI Model Picker — Compare models by context, price, and capabilities
• LLM Requirements Calculator — RAM, VRAM, and hardware needs for local LLMs
• Claude Code Usage Analyzer — Parse and visualize your Claude Code session usage
• Robots.txt Generator — Build a robots.txt (with Content Signals) in seconds
• FindUtils Tool API — REST tool catalog and request reference
• FindUtils MCP Server — MCP connection and tool reference

Frequently asked questions

Does agent-ready mean every agent connects automatically?

No. It means the site provides useful machine-readable interfaces. The client still needs support, configuration, and permission to use them.

Do browser tool slugs always match REST identifiers?

No. Check the generated API catalog. A browser URL or a constructed endpoint is not proof that the service accepts that identifier.

Does Markdown negotiation work on every URL?

The site serves a Markdown sibling when one exists. Check Content-Type and handle an HTML fallback.

Does WebMCP replace the remote MCP server?

No. The optional browser actions and the remote MCP endpoint serve different integrations. Check which one the client supports.

Does a digest prove that a skill is safe?

No. A digest can check that downloaded bytes match the published value. It does not verify the truth or safety of the instructions.

Do Content Signals guarantee training or citations?

No. They state a publisher policy. Provider behavior and other access controls remain separate. Read the current robots file and the provider's documentation.

Where should an agent find the current tool count?

Use the generated API catalog or the live MCP tool listing. Older editorial counts can become stale.