RFC 9727 API Catalog & SEP-1649 MCP Server Cards: Agent-Ready SaaS Guide (2026)

1. Beyond Human Docs: Why Autonomous Agents Need Deterministic Discovery Protocols

In 2024 and 2025, SaaS teams treated developer experience (DX) purely as a human ergonomics challenge: build a polished Mintlify or ReadMe documentation portal, add syntax-highlighted curl snippets, and publish an SDK. In 2026, your primary API consumer is no longer a human engineer reading HTML in Chrome—it is an autonomous coding or workflow agent (Claude Code, Cursor, OpenAI Codex, Meta Muse, or a custom LangGraph orchestrator) tasked with integrating your service on the fly.

When an agent is given nothing more than your root domain (https://signb.ee), how does it discover your OpenAPI 3.1 specification, your Model Context Protocol (MCP) server package, your authentication headers, and your operational health endpoint without burning 50,000 tokens scraping React DOM trees?

As we saw when benchmarking the best e-signature APIs for developers in 2026, legacy enterprise platforms fail agent readiness audits catastrophically. A vendor burdened by the legacy DocuSign API pricing and gated developer sandbox model hides its machine schemas behind multi-step OAuth registration walls and 400-page PDF manuals. By contrast, an agent-native platform exposes a deterministic stack of IETF and MCP discovery endpoints under /.well-known/* so any agent can inspect, bind, and execute tool calls in under 200 milliseconds.

“If an AI agent has to guess whether your OpenAPI spec lives at /swagger.json, /api/openapi.yaml, or /docs/json, your API is invisible to autonomous discovery. RFC 9727 and SEP-1649 do for AI tool discovery what DNS and TLS ALPN did for web transport.”— Michael Beckett, Founder at Signbee

2. The 2026 Agent Readiness Protocol Stack: Complete Specification Matrix

To pass modern agent-readiness benchmarks (including Cloudflare's IsItAgentReady scanner, MCP Registry crawlers, and enterprise RAG indexers), a SaaS application must implement six complementary specifications across its HTTP edge and /.well-known namespace. Every endpoint listed in the matrix below is live in production on Signbee today:

3. Deep Dive: Implementing IETF RFC 9727 (/.well-known/api-catalog) in Next.js

Published by the IETF HTTP APIs (httpapi) Working Group, RFC 9727 (api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs) solves the root-level API discovery problem. RFC 9727 mandates that a server expose an RFC 9264 Linkset serialized as JSON (application/linkset+json) at /.well-known/api-catalog.

Each entry inside the linkset array defines an anchor (the base URL of the API version, such as https://signb.ee/api/v1) along with three standardized IANA link relations:

• service-desc (RFC 8631): Points directly to the machine-readable schema describing the API (e.g., https://signb.ee/openapi.json with type application/openapi+json).
• service-doc (RFC 8631): Points to the human/LLM-readable documentation and Markdown briefing (https://signb.ee/docs and https://signb.ee/llms.txt).
• status (RFC 8631): Points to the real-time JSON health check endpoint (https://signb.ee/api/v1/health) so an autonomous agent can verify service availability before synthesizing tool calls.

In Next.js App Router, folder names beginning with a dot (.well-known) require either a route handler inside src/app/.well-known/api-catalog/route.ts or a rewrite rule in next.config.ts. Here is the exact route handler running in production on Signbee:

import { NextResponse } from "next/server";

/**
 * RFC 9727 API Catalog (/.well-known/api-catalog)
 * Returns an RFC 9264 Linkset (application/linkset+json) describing Signbee's
 * REST API, OpenAPI 3.1 specification, MCP Server Card, and health status endpoints.
 */
export async function GET() {
  const catalog = {
    linkset: [
      {
        anchor: "https://signb.ee/api/v1",
        "service-desc": [
          {
            href: "https://signb.ee/openapi.json",
            type: "application/openapi+json",
            title: "Signbee E-Signature API — OpenAPI 3.1 Specification",
          },
          {
            href: "https://signb.ee/.well-known/openapi.json",
            type: "application/json",
            title: "Signbee OpenAPI 3.1 Specification (Well-Known Mirror)",
          },
        ],
        "service-doc": [
          {
            href: "https://signb.ee/docs",
            type: "text/html",
            title: "Signbee Developer & AI Agent API Documentation",
          },
          {
            href: "https://signb.ee/llms.txt",
            type: "text/markdown",
            title: "Signbee LLM Context & Integration Briefing (llms.txt)",
          },
        ],
        status: [
          {
            href: "https://signb.ee/api/v1/health",
            type: "application/json",
            title: "Signbee API Health & Readiness Status",
          },
        ],
        describedby: [
          {
            href: "https://signb.ee/.well-known/mcp/server-card.json",
            type: "application/json",
            title: "Signbee MCP Server Card (SEP-1649)",
          },
          {
            href: "https://signb.ee/.well-known/ai-plugin.json",
            type: "application/json",
            title: "Signbee AI Plugin & Agent Manifest",
          },
        ],
      },
    ],
  };

  return new NextResponse(JSON.stringify(catalog, null, 2), {
    status: 200,
    headers: {
      "Content-Type": "application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"",
      "Cache-Control": "public, max-age=3600, s-maxage=3600",
      "Access-Control-Allow-Origin": "*",
      Link: '<https://signb.ee/openapi.json>; rel="service-desc"; type="application/openapi+json", <https://signb.ee/docs>; rel="service-doc"; type="text/html"',
    },
  });
}

Notice the Content-Type header: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727". Returning plain application/json without the linkset+json media type and profile parameter will cause strict RFC 9727 validators to flag a schema conformance warning.

4. Deep Dive: SEP-1649 MCP Server Cards (/.well-known/mcp/server-card.json)

While RFC 9727 exposes REST and OpenAPI descriptions, the Model Context Protocol (MCP) ecosystem required a parallel zero-configuration discovery mechanism so IDE agents and desktop assistants could discover a domain's official MCP server without forcing the developer to hunt through GitHub READMEs.

SEP-1649 (MCP Server Cards) solves this by defining a static JSON manifest at /.well-known/mcp/server-card.json. Unlike a live JSON-RPC transport socket, the Server Card is a cacheable metadata document that declares:

1. Server Identity & Registry Package: The canonical server name (io.github.mjcbeckett/signbee-mcp), npm package (signbee-mcp), and zero-install invocation command (npx -y signbee-mcp).
2. Transport & Authentication Requirements: Supported transports (stdio and http) alongside optional or required environment variables (SIGNBEE_API_KEY) and registration URLs.
3. Complete Tool Input Schemas: The full JSON Schema definition of every MCP tool exposed by the server (send_document, get_document_status, list_documents) so an agent planner can evaluate whether the MCP server satisfies a user's goal before spawning the child process.

Even if teams are evaluating an open-source e-signature API comparison or looking for an affordable e-signature API integration, having a first-party SEP-1649 Server Card means Claude Code or Cursor can wire up the entire integration from a single domain reference. Here is Signbee's production SEP-1649 route handler:

import { NextResponse } from "next/server";

export async function GET() {
  const serverCard = {
    $schema: "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
    protocolVersion: "2025-06-18",
    serverInfo: {
      name: "io.github.mjcbeckett/signbee-mcp",
      title: "Signbee E-Signature MCP Server",
      version: "1.1.0",
      description:
        "Send legally binding contracts, NDAs, and documents for e-signature directly from AI agents. Supports CommonMark Markdown and pre-existing PDFs with SHA-256 tamper-evident certificates.",
      homepage: "https://signb.ee",
      documentationUrl: "https://signb.ee/docs",
      repository: {
        url: "https://github.com/mjcbeckett/signbee-mcp",
        source: "github",
      },
    },
    packages: [
      {
        registryType: "npm",
        identifier: "signbee-mcp",
        version: "1.1.0",
        transport: {
          type: "stdio",
          command: "npx",
          args: ["-y", "signbee-mcp"],
        },
        environmentVariables: [
          {
            name: "SIGNBEE_API_KEY",
            description:
              "Optional Signbee API key (signbee_...) for pre-verified autonomous sending.",
            isRequired: false,
            isSecret: true,
          },
        ],
      },
    ],
    capabilities: {
      tools: { listChanged: false },
    },
    authentication: {
      type: "bearer",
      optional: true,
      headerChoices: ["Authorization: Bearer <SIGNBEE_API_KEY>", "X-API-Key: <SIGNBEE_API_KEY>"],
      registrationUrl: "https://signb.ee/register",
    },
    tools: [
      {
        name: "send_document",
        description:
          "Send a contract or agreement for e-signature via Signbee (Markdown or base64 PDF).",
        inputSchema: {
          type: "object",
          required: ["title", "sender_name", "sender_email", "recipient_name", "recipient_email"],
          properties: {
            title: { type: "string", description: "Document title" },
            markdown: { type: "string", description: "Contract body in CommonMark markdown" },
            pdf_base64: { type: "string", description: "Base64-encoded PDF bytes" },
            sender_name: { type: "string" },
            sender_email: { type: "string", format: "email" },
            recipient_name: { type: "string" },
            recipient_email: { type: "string", format: "email" },
          },
        },
      },
    ],
  };

  return NextResponse.json(serverCard, {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "public, max-age=3600, s-maxage=3600",
      "Access-Control-Allow-Origin": "*",
    },
  });
}

5. Procedural Memory: Agent Skills Discovery v0.2.0 with SHA-256 Digests

Giving an AI agent an OpenAPI spec or MCP tool schema teaches it the syntax of your API, but not the domain heuristics. For example, when drafting a two-party commercial contract, an agent benefits enormously from knowing how Signbee renders CommonMark Markdown tables, how to structure signature recitals, and how to poll or receive webhooks when Party B completes the ceremony.

The Agent Skills Discovery RFC v0.2.0 (/.well-known/agent-skills/index.json) bridges this gap by publishing a cryptographically hashed index of procedural SKILL.md artifacts. At runtime, your Next.js route computes the real-time sha256:... digest of each skill Markdown buffer so enterprise agent sandboxes can verify that the procedural instructions have not been tampered with in transit.

6. Edge Content Negotiation: Accept: text/markdown & RFC 8288 Link Headers in middleware.ts

Even when you publish /.well-known/api-catalog and /.well-known/mcp/server-card.json, two critical edge cases remain:

1. Deep-Link Discovery (RFC 8288): An agent might be pointed directly at a blog post, a white-label integration guide such as our white-label e-signature API architecture, or your pricing page. By attaching an HTTP Link header to every page response, the agent discovers your API catalog from any URL on your domain.
2. Markdown Content Negotiation (Accept: text/markdown): When an LLM agent requests your homepage or documentation with Accept: text/markdown, returning a 120 KB Next.js HTML payload wastes context window tokens and increases time-to-first-token latency. Rewriting those requests in src/middleware.ts to a clean CommonMark response with Vary: Accept slashes token usage by 90%.

import { NextRequest, NextResponse } from "next/server";

const AGENT_DISCOVERY_LINKS = [
  '<https://signb.ee/.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"',
  '<https://signb.ee/openapi.json>; rel="service-desc"; type="application/openapi+json"',
  '<https://signb.ee/docs>; rel="service-doc"; type="text/html"',
  '<https://signb.ee/llms.txt>; rel="llms-txt"; type="text/markdown"',
  '<https://signb.ee/.well-known/mcp/server-card.json>; rel="mcp-server-card"; type="application/json"',
  '<https://signb.ee/.well-known/agent-skills/index.json>; rel="agent-skills"; type="application/json"',
].join(", ");

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const acceptHeader = request.headers.get("accept") || "";

  // 1. Content Negotiation: Serve clean CommonMark when AI agents request text/markdown
  const wantsMarkdown =
    acceptHeader.includes("text/markdown") || acceptHeader.includes("text/x-markdown");

  if (wantsMarkdown && (pathname === "/" || pathname === "/docs" || pathname === "/pricing")) {
    const markdownUrl = request.nextUrl.clone();
    markdownUrl.pathname = "/api/markdown";
    markdownUrl.searchParams.set("path", pathname);

    const response = NextResponse.rewrite(markdownUrl);
    response.headers.set("Link", AGENT_DISCOVERY_LINKS);
    response.headers.set("Vary", "Accept");
    return response;
  }

  // 2. Attach RFC 8288 Link Discovery Headers to all standard HTML/API responses
  const response = NextResponse.next();
  response.headers.set("Link", AGENT_DISCOVERY_LINKS);
  response.headers.set("Vary", "Accept");
  return response;
}

7. Production Telemetry: HTML DOM Scraping vs. Agent-Ready Discovery

How much faster and cheaper does an AI agent operate when a SaaS platform implements RFC 9727, SEP-1649, and Accept: text/markdown negotiation? We benchmarked Claude 4.5 Sonnet and GPT-5 agent loops executing a cold contract dispatch task against Signbee before and after deploying the full agent-readiness stack:

8. Verifying Your Agent-Ready Endpoints with curl & Content-Signal

The final piece of the 2026 discovery stack is updating /robots.txt with the Content-Signal: ai-train=yes, search=yes, ai-input=yes declaration and verifying that /.well-known/* paths are explicitly allowed for all user agents. Whether developers are comparing our 2026 e-signature API pricing breakdown or testing our free e-signature API tier, any engineer or autonomous agent can validate Signbee's live discovery stack right now with four terminal commands:

# 1. Inspect RFC 8288 Link headers and Markdown Content Negotiation
curl -i -H "Accept: text/markdown" https://signb.ee/

# 2. Fetch IETF RFC 9727 API Catalog (application/linkset+json)
curl -s https://signb.ee/.well-known/api-catalog | jq .

# 3. Fetch MCP SEP-1649 Server Card
curl -s https://signb.ee/.well-known/mcp/server-card.json | jq .

# 4. Fetch Agent Skills Discovery v0.2.0 Manifest with SHA-256 Digests
curl -s https://signb.ee/.well-known/agent-skills/index.json | jq .

Frequently Asked Questions: RFC 9727, SEP-1649 & Agent Readiness