Agent Readiness

Zuse Bifrost publishes a small set of well-known documents so that a client, a crawler or an AI agent that knows nothing about Zuse Bifrost can fetch one URL and learn which APIs exist, where each one's machine-readable description is, how to authenticate, where its documentation lives and where to check that it is up. Every document is built from the running application's configuration, the MCP server's own declarations and the tool catalogue, so none of them can name a host, a version or a count that the deployment does not have.

The addresses below are written as https://app.example.test for the application, https://api.example.test for the API host and https://mcp.example.test for the MCP server; your workspace's addresses are the ones your administrator shares.

All of them answer GET, carry Cache-Control: public, max-age=3600, need no credentials and may be read from any origin (Access-Control-Allow-Origin: *), so a validator or an agent running in a browser can fetch them.

API catalogCopy Anchor Link

The catalog is the discovery document defined by RFC 9727. It lives on the application's address and is answered on the API host as well, for clients that start there:

The response is served as application/linkset+json with the RFC 9727 profile parameter and may be cached for an hour.

curl -s https://app.example.test/.well-known/api-catalog | jq

The documentCopy Anchor Link

The catalog is a Linkset: one entry per API, each anchored on the URL that represents the API and carrying typed links.

{
  "linkset": [
    {
      "anchor": "https://api.example.test/v1",
      "service-desc": [
        {
          "href": "https://api.example.test/openapi.json",
          "type": "application/vnd.oai.openapi+json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.test/api/v1", "type": "text/html" },
        { "href": "https://docs.example.test/webhooks/v1", "type": "text/html" }
      ],
      "status": [{ "href": "https://api.example.test/up" }]
    },
    {
      "anchor": "https://mcp.example.test",
      "service-doc": [
        { "href": "https://docs.example.test/mcp/v1", "type": "text/html" }
      ],
      "service-meta": [
        {
          "href": "https://mcp.example.test/.well-known/oauth-protected-resource",
          "type": "application/json"
        },
        {
          "href": "https://app.example.test/.well-known/mcp/server-card.json",
          "type": "application/json"
        }
      ],
      "status": [{ "href": "https://app.example.test/up" }]
    }
  ]
}

What each relation points toCopy Anchor Link

MCP server cardCopy Anchor Link

The server card follows the shape proposed for MCP discovery in SEP-1649, and names the server at its top level (name in the registry's reverse-DNS form, title, description, version, websiteUrl) the way a registry listing does. It is deliberately small: identity, transport, protocol versions, authentication and capability flags with counts. The tool catalogue itself is linked (toolCatalogUrl), not copied, because the server describes its tools to a connected client over the protocol.

It is served on the application's address and, when the MCP server has an address of its own, there as well:

{
  "name": "test.example.app/mcp",
  "title": "Zuse Bifrost MCP Server",
  "description": "…",
  "version": "1.0.0",
  "websiteUrl": "https://app.example.test",
  "serverInfo": {
    "name": "Zuse Bifrost",
    "title": "Zuse Bifrost MCP Server",
    "version": "1.0.0",
    "description": "…",
    "websiteUrl": "https://app.example.test"
  },
  "protocolVersion": "2025-06-18",
  "supportedProtocolVersions": ["2025-06-18", "2025-03-26"],
  "transport": {
    "type": "streamable-http",
    "endpoint": "https://mcp.example.test"
  },
  "remotes": [{ "type": "streamable-http", "url": "https://mcp.example.test" }],
  "authentication": {
    "schemes": ["oauth2", "bearer"],
    "resourceMetadataUrl": "https://mcp.example.test/.well-known/oauth-protected-resource",
    "authorizationServers": ["https://app.example.test"],
    "scopes": ["mcp:use"]
  },
  "capabilities": {
    "tools": { "listChanged": false, "count": 26 },
    "resources": { "listChanged": false, "count": 3 },
    "prompts": { "listChanged": false, "count": 0 }
  },
  "documentationUrl": "https://docs.example.test/mcp/v1",
  "toolCatalogUrl": "https://api.example.test/mcp-tools.json"
}

Every field is read from the server class, the package and the catalogue: the protocol versions are the ones the server negotiates, the listChanged flags are the ones it declares, and the counts are the live tool and resource registrations, so the card says exactly what the initialize handshake would. The versions and counts above are illustrative; read the card for the current ones.

Agent skillsCopy Anchor Link

A skill is a short instruction file, SKILL.md, that an agent loads when it needs to work with Zuse Bifrost. The index follows the Agent Skills Discovery RFC 0.2.0 and lists three skills:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "zusegenius-rest-api",
      "type": "skill-md",
      "description": "Call the Zuse Bifrost REST API: authenticate with a personal access token, page through lists, send an Idempotency-Key on every write, honour the rate limits and read the OpenAPI document.",
      "url": "https://app.example.test/.well-known/agent-skills/zusegenius-rest-api/SKILL.md",
      "digest": "sha256:…"
    }
  ]
}

Each file opens with YAML front matter carrying the same name and description as the index, followed by Markdown instructions. The digest is the SHA-256 of the exact bytes the file's URL serves, so a client can check that what it loaded is what the index promised. The instructions are generated from the application's configuration and the constants that enforce each rule: the hosts, the page-size ceiling, the idempotency window, the rate limits, the webhook retry schedule and the tool and event counts are the running values, never typed into the text.

curl -s https://app.example.test/.well-known/agent-skills/zusegenius-mcp/SKILL.md

OpenID Connect discovery aliasCopy Anchor Link

Some clients look for an authorization server's metadata only at the OpenID Connect discovery path. The authorization server (the application's address) therefore answers /.well-known/openid-configuration with the same RFC 8414 document it serves at /.well-known/oauth-authorization-server: the issuer, the authorization, token and dynamic-registration endpoints, the code response type, S256 as the only PKCE method, the mcp:use scope and the authorization_code and refresh_token grants. It is an OAuth 2.0 document at the OpenID Connect path, not an OpenID provider: there is no jwks_uri and no ID token. Both metadata documents and the dynamic registration endpoint can be called from a client running in a browser. See MCP authentication for the flow.

AGENTS.mdCopy Anchor Link

https://app.example.test/AGENTS.md (also /agents.md and /.well-known/AGENTS.md) is the briefing an agent reads first: what Zuse Bifrost is as a service, the two ways to a credential, the REST API, the MCP server and the webhooks in a paragraph each, the conventions every surface shares, the operations that need a human before they run, what never to do, and where every longer document is. Like the skills, every address, count and limit in it is read from the running application.

curl -s https://app.example.test/AGENTS.md

llms.txtCopy Anchor Link

The application serves https://app.example.test/llms.txt so a crawler that starts at the application's address finds the product described for language models: it points at this documentation's /llms.txt (every page with a one-line summary) and /llms-full.txt (the text of every page in one file), and lists the machine-readable documents on this page. The application's own screens are never served as prose to a model; the documentation is the text.

Using it from an agentCopy Anchor Link

An agent that is handed the application's address and nothing else can resolve the whole surface in two requests: the catalog, then the OpenAPI document it points at. From there every operation, its abilities, its errors and the webhook events are described, and the quickstart explains how to obtain a token. An agent that speaks MCP instead reads the server card or follows the catalog's second entry to the MCP guide and connects with OAuth or a personal access token. An agent that works from skill files loads the three skills and has the rules of each surface in a page apiece; one that reads briefings loads AGENTS.md and has all of it on one page.

See alsoCopy Anchor Link

• OpenAPI Specification, the document the catalog's service-desc link points at.
• MCP authentication, the OAuth flow the metadata documents describe.
• MCP tools reference, the catalogue the server card links.