NOMCP: No-Overhead Machine-Consumable Protocol

Abstract

This document specifies NOMCP (No-Overhead Machine-Consumable Protocol), a minimal standard for exposing APIs that are simultaneously human-readable and machine-readable. NOMCP leverages existing web standards—HTTP, HTML, and capability URLs—to enable Large Language Models (LLMs) and other automated agents to discover and consume APIs without custom protocols, SDKs, or complex authentication flows.

Status of This Memo

This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements.

Copyright Notice

This document is released into the public domain.

1. Introduction

The proliferation of LLM-based agents has created demand for APIs that can be discovered and consumed without prior integration work. Existing solutions introduce significant complexity: custom protocols, elaborate tool schemas, separate authentication mechanisms, and purpose-built SDKs.

NOMCP takes a different approach. It observes that the web already provides all necessary primitives:

• HTTP for transport
• HTML for human-and-machine-readable documentation
• Capability URLs for embedded authentication and authorization

NOMCP is not a new protocol. It is a convention for using existing protocols in a way that makes APIs self-describing and immediately consumable by both humans and machines.

1.1 Motivation

An LLM with access to an HTTP client should be able to:

1. Receive a single URL
2. Fetch that URL
3. Read the response
4. Understand what operations are available
5. Perform those operations

No SDK installation. No API key management. No schema parsing. No protocol translation.

NOMCP achieves this by making the API documentation be the API entry point.

2. Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Service Document

The HTML document returned at the root of a NOMCP endpoint, describing available operations.

Capability URL

A URL containing an embedded token that grants specific permissions, requiring no additional authentication.

Consumer

Any client consuming the API, whether human (via browser), LLM agent, or traditional software.

3. Design Goals

NOMCP is designed around the following principles:

1. Zero Configuration: A consumer needs only a URL to begin.
2. Human Legibility: All machine-readable content MUST be human-readable.
3. Web Native: Use only existing web standards; introduce no new protocols.
4. Stateless Discovery: The service document MUST contain all information needed to use the API.
5. Scoped by Default: Capability URLs encode their own permissions; no ambient authority.

4. Specification

4.1 Capability URLs

A NOMCP endpoint is identified by a Capability URL of the following form:

https://{host}/{token}/
https://{host}/{token}/{path}

Where:

• {host} is the API hostname
• {token} is an opaque string encoding authentication and authorization
• {path} is an optional path to a specific resource or operation

The token MUST:

• Be URL-safe (alphanumeric, hyphen, underscore)
• Encode sufficient information for the server to authenticate and authorize requests
• Be treated as a secret by consumers

The token SHOULD:

• Be scoped to specific operations, resources, or time windows
• Be revocable by the issuing service
• Include an identifier component for logging/auditing (e.g., usr_alice_abc123)

The token MAY:

• Be cryptographically signed (e.g., JWT) or be an opaque lookup key
• Include human-readable components indicating scope (e.g., readonly_, workspace-5_)

4.1.1 Token Placement

The token MUST appear as the first path segment after the host. This ensures:

• Simple URL parsing
• Consistent routing
• Clear visual identification

Alternative placements (query parameters, subdomains) are NOT RECOMMENDED as they complicate parsing and are more likely to be logged or leaked.

4.1.2 Trailing Slash

The root capability URL SHOULD include a trailing slash. Servers MUST accept requests both with and without the trailing slash and SHOULD redirect to the canonical form.

4.2 Service Document

A GET request to the root capability URL MUST return a Service Document.

4.2.1 Content Type

The Service Document MUST be served as text/html by default.

4.2.2 Required Content

The Service Document MUST include:

1. Title: A human-readable name for the API or service
2. Description: A brief explanation of what the API does
3. Scope Statement: What this particular token is authorized to do
4. Endpoint List: All available operations

The Service Document SHOULD include:

1. Rate Limit Information: Applicable limits for this token
2. Expiration: When/if this token expires
3. Contact Information: How to get help or report issues

4.2.3 HTML Structure

The Service Document SHOULD use semantic HTML elements:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{API Title}</title>
</head>
<body>
  <h1>{API Title}</h1>
  
  <section id="description">
    <p>{API description}</p>
  </section>
  
  <section id="scope">
    <h2>Access Scope</h2>
    <p>{What this token can do}</p>
  </section>
  
  <section id="endpoints">
    <h2>Endpoints</h2>
    <!-- Endpoint descriptions here -->
  </section>
</body>
</html>

Servers MAY include CSS for improved human readability, but MUST ensure the document is fully understandable without styling.

4.3 Endpoint Descriptions

Each endpoint MUST be described with:

1. Method: HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
2. Path: Relative path from the capability URL root
3. Description: What the operation does

Each endpoint SHOULD be described with:

1. Parameters: Path parameters, query parameters, or request body fields
2. Response: Expected response format and fields
3. Errors: Possible error conditions
4. Example: At least one request/response example

4.3.1 Endpoint HTML Structure

Endpoints SHOULD be marked up as follows:

<article class="endpoint" data-method="POST" data-path="/messages">
  <h3><code>POST /messages</code></h3>
  
  <p>Send a message to a channel.</p>
  
  <section class="parameters">
    <h4>Parameters</h4>
    <dl>
      <dt><code>channel</code> (string, required)</dt>
      <dd>The channel ID to post to</dd>
      
      <dt><code>text</code> (string, required)</dt>
      <dd>The message content</dd>
      
      <dt><code>thread_id</code> (string, optional)</dt>
      <dd>Reply to a specific thread</dd>
    </dl>
  </section>
  
  <section class="response">
    <h4>Response</h4>
    <pre><code>{
  "id": "msg_123",
  "timestamp": "2025-01-15T10:30:00Z"
}</code></pre>
  </section>
  
  <section class="example">
    <h4>Example</h4>
    <pre><code>POST /messages
Content-Type: application/json

{"channel": "general", "text": "Hello!"}</code></pre>
  </section>
</article>

4.3.2 Data Attributes

Endpoints SHOULD include data-method and data-path attributes on container elements to facilitate programmatic parsing. However, consumers MUST NOT rely solely on these attributes; the document MUST be understandable from its text content alone.

4.4 Content Negotiation

While the Service Document MUST be available as HTML, servers MAY support content negotiation via the Accept header:

The HTML representation is REQUIRED. Other representations are OPTIONAL and MUST contain equivalent information.

5. Security Considerations

5.1 Token Secrecy

Capability URLs contain secrets. Consumers and intermediaries MUST treat them accordingly:

• MUST NOT log full capability URLs
• MUST NOT include in Referer headers (servers SHOULD set Referrer-Policy: no-referrer)
• MUST NOT store in browser history unnecessarily
• SHOULD transmit only over HTTPS

5.2 Token Scope

Tokens SHOULD be scoped to the minimum permissions required:

• Resource Scope: Limit to specific resources (e.g., one workspace, one document)
• Operation Scope: Limit to specific operations (e.g., read-only)
• Time Scope: Expire after a reasonable duration
• Rate Scope: Limit request rates

5.3 Token Revocation

Services MUST provide a mechanism to revoke tokens. Services SHOULD allow revocation of:

• Individual tokens
• All tokens for a user
• All tokens matching certain criteria (e.g., all read-write tokens)

5.4 HTTPS Requirement

NOMCP endpoints MUST be served over HTTPS. HTTP without TLS MUST NOT be used in production.

5.5 Leakage Vectors

Services should be aware of common URL leakage vectors:

• Referer headers (mitigate with Referrer-Policy)
• Browser history (consider short-lived tokens for browser use)
• Logs (strip or mask tokens in logs)
• Copy/paste accidents (include clear "secret" indicators in token format)

5.6 Token Format Recommendations

Tokens SHOULD include a prefix indicating their sensitivity and scope:

{provider}_{scope}_{random}

Examples:
  nomcp_ro_abc123def456      # read-only
  nomcp_rw_xyz789ghi012      # read-write
  nomcp_tmp_1hr_mno345pqr    # temporary, 1 hour

This aids in:

• Identifying leaked tokens in logs
• Understanding scope without server lookup
• Automated secret scanning

6. Examples

6.1 Minimal Service Document

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Notes API</title>
</head>
<body>
  <h1>Notes API</h1>
  <p>A simple note-taking service.</p>
  
  <h2>Scope</h2>
  <p>This token has <strong>read/write</strong> access to the notebook "Work".</p>
  
  <h2>Endpoints</h2>
  
  <h3><code>GET /notes</code></h3>
  <p>List all notes. Returns JSON array of note objects.</p>
  
  <h3><code>GET /notes/{id}</code></h3>
  <p>Get a single note by ID.</p>
  
  <h3><code>POST /notes</code></h3>
  <p>Create a new note.</p>
  <p>Body: <code>{"title": "...", "content": "..."}</code></p>
  
  <h3><code>PUT /notes/{id}</code></h3>
  <p>Update an existing note.</p>
  <p>Body: <code>{"title": "...", "content": "..."}</code></p>
  
  <h3><code>DELETE /notes/{id}</code></h3>
  <p>Delete a note.</p>
</body>
</html>

6.2 LLM Interaction Example

An LLM agent receiving a NOMCP URL might operate as follows:

User: Add "Buy milk" to my todo list. Here's the API: https://api.todos.io/tok_rw_abc123/

Agent: [Fetches https://api.todos.io/tok_rw_abc123/]
       [Reads Service Document, finds POST /todos endpoint]
       [Sends POST https://api.todos.io/tok_rw_abc123/todos with {"title": "Buy milk"}]
       [Receives {"id": "todo_789", "title": "Buy milk", "done": false}]

Agent: Done! I've added "Buy milk" to your todo list.

7. References

7.1 Normative References

• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
• RFC 7230: HTTP/1.1 Message Syntax and Routing
• RFC 7231: HTTP/1.1 Semantics and Content
• HTML Living Standard: https://html.spec.whatwg.org/

7.2 Informative References

• Capability URLs: https://www.w3.org/TR/capability-urls/
• RFC 8615: Well-Known URIs
• RFC 6749: OAuth 2.0 Authorization Framework

8. Acknowledgments

NOMCP is inspired by the observation that the simplest protocols are often the most durable. The web has proven itself over decades; NOMCP merely suggests we keep using it.

Appendix A: Design Rationale

A.1 Why HTML?

HTML is:

1. Universal: Every HTTP client can fetch it; every browser can render it
2. Human-readable: Unlike JSON Schema, humans can read HTML without tooling
3. LLM-friendly: LLMs are trained extensively on HTML and understand it natively
4. Extensible: Additional semantics can be added without breaking consumers

A.2 Why Capability URLs?

Traditional API authentication requires:

1. Obtaining credentials (API key, OAuth tokens)
2. Storing credentials securely
3. Attaching credentials to requests (headers, query params)
4. Handling credential refresh

Capability URLs collapse this into "have the URL or don't." This is:

• Simpler: One string contains everything needed
• Scopeable: Each URL can have different permissions
• Shareable: Give someone limited access by giving them a limited URL
• Revocable: Revoke the URL, revoke the access

A.3 Why Not OpenAPI/JSON Schema?

OpenAPI is excellent for code generation and formal tooling. However:

1. It requires parsing a complex schema format
2. It's not human-readable without tooling
3. LLMs handle prose documentation better than formal schemas
4. It separates documentation from the API itself

NOMCP prioritizes immediate usability over formal completeness.

Appendix B: Implementation Notes

B.1 Server Implementation

A minimal NOMCP server needs to:

1. Parse the token from the first path segment
2. Validate the token and extract scope
3. Serve the Service Document at the root
4. Handle API requests at sub-paths

B.2 Client Implementation

A minimal NOMCP client needs to:

1. Fetch the root URL
2. Parse the HTML (or just read it, for LLMs)
3. Construct requests to described endpoints

B.3 Token Generation

Tokens can be implemented as:

• Opaque IDs: Random strings mapped to permissions in a database
• Signed tokens: JWTs or similar containing encoded permissions
• Hybrid: Prefix + random ID, where prefix hints at scope

End of Document