# NOMCP: No-Overhead Machine-Consumable Protocol
```
RFC: XXXX
Category: Standards Track
Author: [TBD]
Date: January 2026
```
## 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.
---
## Table of Contents
1. [Introduction](#1-introduction)
2. [Terminology](#2-terminology)
3. [Design Goals](#3-design-goals)
4. [Specification](#4-specification)
- 4.1 [Capability URLs](#41-capability-urls)
- 4.2 [Service Document](#42-service-document)
- 4.3 [Endpoint Descriptions](#43-endpoint-descriptions)
- 4.4 [Content Negotiation](#44-content-negotiation)
5. [Security Considerations](#5-security-considerations)
6. [Examples](#6-examples)
7. [References](#7-references)
8. [Acknowledgments](#8-acknowledgments)
---
## 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:
```html
{API Title}
{API Title}
Access Scope
{What this token can do}
```
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:
```html
POST /messages
Send a message to a channel.
Parameters
channel (string, required)- The channel ID to post to
text (string, required)- The message content
thread_id (string, optional)- Reply to a specific thread
Response
{
"id": "msg_123",
"timestamp": "2025-01-15T10:30:00Z"
}
Example
POST /messages
Content-Type: application/json
{"channel": "general", "text": "Hello!"}
```
#### 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:
| Accept Header | Response Format |
|--------------|-----------------|
| `text/html` (default) | HTML Service Document |
| `application/json` | JSON representation (optional) |
| `text/plain` | Plain text representation (optional) |
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
```html
Notes API
Notes API
A simple note-taking service.
Scope
This token has read/write access to the notebook "Work".
Endpoints
GET /notes
List all notes. Returns JSON array of note objects.
GET /notes/{id}
Get a single note by ID.
POST /notes
Create a new note.
Body: {"title": "...", "content": "..."}
PUT /notes/{id}
Update an existing note.
Body: {"title": "...", "content": "..."}
DELETE /notes/{id}
Delete a note.
```
### 6.2 Complete Service Document
```html
Acme Messaging API
Acme Messaging API
Send and receive messages across your organization.
Access Scope
- Workspace: Engineering
- Permissions: read, write
- Rate limit: 100 requests/minute
- Expires: 2025-02-01T00:00:00Z
Endpoints
GET /channels
List channels you have access to.
Query Parameters
limit (integer, optional, default: 20)- Maximum number of channels to return
cursor (string, optional)- Pagination cursor from previous response
Response
{
"channels": [
{"id": "ch_123", "name": "general", "member_count": 42}
],
"next_cursor": "abc123"
}
POST /messages
Send a message to a channel.
Request Body
channel_id (string, required)- Target channel ID
text (string, required)- Message content (max 4000 characters)
thread_id (string, optional)- Thread to reply to
Example
POST /messages
Content-Type: application/json
{
"channel_id": "ch_123",
"text": "Hello, team!"
}
Response
{
"id": "msg_456",
"channel_id": "ch_123",
"text": "Hello, team!",
"author": "usr_789",
"timestamp": "2025-01-15T10:30:00Z"
}
Errors
400 Bad Request- Invalid request body
403 Forbidden- Cannot post to this channel
404 Not Found- Channel does not exist
Error Format
All errors return JSON:
{
"error": {
"code": "invalid_request",
"message": "Human-readable description"
}
}
```
### 6.3 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*