Mu

MUCP HTTPS binding

MUCP HTTPS/JSON binding

Status: working specification of mucp/1. Read with the core. Requirement IDs below are referenced by the conformance plan. This document defines the wire binding, not an assistant or service implementation.

1. Endpoint and transport (HTTP-01)

A configured server origin identifies the endpoint: https://example.net/. HTTPS is REQUIRED except for local development over HTTP on loopback. Clients MUST validate TLS certificates and MUST NOT follow redirects for authenticated calls. This binding uses HTTP semantics from RFC 9110; it does not define a new TCP protocol or require HTTP/1.1 rather than HTTP/2 or HTTP/3.

GET / with Micro-Protocol: mucp/1 discovers the primary contract. POST / invokes an operation. Discovery does not require credentials. Invocation requires authentication as defined by the server’s security profile. Other methods return 405 with Allow: GET, POST after MUCP routing. Mu retains /mucp as a compatibility alias. Requests without the protocol header at / belong to the website and are outside this binding, not an anonymous invocation fallback.

2. Invocation metadata (HTTP-02)

Header Requirement
Micro-Protocol Exactly mucp/1
Micro-Service Exact service name defined by the selected contract
Micro-Endpoint Exact endpoint name defined by the selected contract
Micro-Id 16–128 ASCII letters, digits, hyphens or underscores
Content-Type application/json; media-type parameters may be present

All five headers MUST occur once. HTTP field names are case-insensitive; routing values are case-sensitive. A duplicate field line MUST be rejected, including Content-Type. A comma-joined routing value is not a list of alternatives. Unknown service/endpoint pairs return 404, not a successful empty result. Unknown protocol versions return 400. No general service-name grammar is imposed beyond valid HTTP field values and exact matching to a supported contract in this version.

Missing/duplicate routing fields return 400 invalid_headers. Missing or invalid Content-Type returns 415 unsupported_encoding; duplicate Content-Type returns 400 invalid_headers. Invalid IDs return 400 invalid_id.

Other HTTP fields do not establish identity or modify operation meaning. A contract extension must document any additional protocol fields; arbitrary headers MUST NOT be propagated as tool credentials or instructions.

3. Body encoding (HTTP-03)

The body MUST be one UTF-8 JSON object using the selected contract’s protobuf JSON mapping. The limit is 65,536 body bytes, inclusive. This is the unwrapped request message, not a serialized metadata/body envelope. This binding defines no compressed-request-body support; clients send uncompressed JSON.

Protobuf JSON defines lowerCamelCase names (or explicit json_name), string-encoded 64-bit integers, base64 bytes and RFC 3339 timestamps. It also defines accepted proto field-name aliases, omitted defaults, null values and enum representations. A contract may impose stricter semantic validation, such as rejecting unknown or unspecified access modes. Unknown fields, duplicate fields, multiple objects, invalid JSON and a non-object root MUST be rejected with 400 invalid_arguments. An oversized body returns 413 too_large. Authentication may reject a call before its body is parsed; clients MUST NOT depend on an error precedence for requests with multiple independent faults.

Responses use the same protobuf JSON mapping. Clients MUST tolerate additive response fields and MUST NOT depend on field ordering or whitespace. A contract specifies any fallback for unknown result variants. Implementations may include or omit default-valued fields in accordance with protobuf JSON semantics.

4. Discovery (HTTP-04)

Successful discovery is HTTP 200 with application/json and Micro-Protocol: mucp/1. It has no invocation correlation ID. The JSON object has these fields:

Field Type and meaning
protocol String, exactly mucp/1
service Nonempty string, primary routing service
contract Nonempty string, versioned contract identifier
encoding String, protobuf-json
operations Array of endpoint strings supported for the primary service
features Optional object mapping feature names to booleans
limits Optional object mapping limit names to nonnegative integers

Unknown response fields/features/limits MUST be tolerated. Missing optional fields MUST NOT be interpreted as support. Operation order has no meaning. Discovery MUST NOT contain account-private data and MUST NOT imply authorization. Secondary service discovery is contract-defined; this version does not pretend the primary operations array inventories every service on the instance.

Mu’s discovery values and authenticated service catalogue are defined in the runtime profile. A different implementation can expose a different primary service and contract. Mu’s current handler still hard-codes its primary discovery profile; extracting generic discovery into configurable go-micro code is follow-up implementation work.

5. Invocation responses (HTTP-05)

A successful invocation MUST return HTTP 200, application/json, a JSON object and exact echoes of Micro-Protocol, Micro-Service, Micro-Endpoint and Micro-Id. Clients MUST verify protocol and correlation before accepting the result. Response metadata is not repeated in the body. Mu sets Cache-Control: private, no-store; servers implementing this binding MUST prevent shared caching of private results.

An error before valid routing/correlation is established may omit echoes. Clients MUST handle non-2xx status even if a proxy returns an unstructured body. A response that cannot be validated is an uncertain outcome, never proof that a mutation was not executed. There is no automatic redirect, version downgrade or retry mechanism in the binding.

6. Authentication boundary (HTTP-06)

Bearer calls use Authorization: Bearer <token> and do not carry cookies. Credentials are obtained out of band or through a separately specified OAuth profile. A valid-looking routing header or body field does not authenticate a caller. Servers MUST reject invalid explicit credentials rather than falling back to another identity such as a cookie session.

Cookie authentication, OAuth bootstrap, exact scope names, CSRF and CORS policy are deployment/profile concerns. Mu’s profile defines them in accounts and sign-in. A client cannot assume Mu’s OAuth URLs or token lifetimes apply to an arbitrary MUCP server. Authorization MUST be checked per operation and resource, including recovery reads.

7. Errors (HTTP-07)

A binding-generated error is a non-2xx HTTP response with application/json, Micro-Error: <code> and the object:

{"error":{"code":"invalid_arguments","message":"Invalid request","status":400}}

code is a machine-readable string; message is display text; status equals the HTTP status. Unknown codes MUST be handled using HTTP status without replaying a mutation. Error messages MUST NOT be parsed to decide behaviour or executed as HTML.

Status Binding codes / meaning
400 invalid_headers, unsupported_protocol, invalid_id, invalid_arguments
401 unauthenticated; obtain valid credentials
403 forbidden, csrf; authority insufficient
404 not_found; unknown operation or inaccessible resource
405 method_not_allowed
413 too_large
415 unsupported_encoding
429 rate_limited; do not automatically replay a mutation
500 execution_failed, encoding_failed; outcome may be uncertain

Contracts add operation-specific codes/statuses. Mu uses 402 for credits, 409 for submission conflicts and 504 for an unfinished synchronous wait. These are not requirements to implement a payment system or an assistant in every MUCP server.

Compatibility exception: Mu’s existing product authorization gate sets Micro-Error: authorization_failed but may return a string-valued error rather than the object above. Clients MUST handle that response by status. Uniform structured authentication errors are a known gap, not a claim this PR fixes. Intermediary failures may omit both the code and JSON body entirely.

8. Recovery and flow control (HTTP-08)

The binding does not make POST idempotent. Only an operation contract can permit replay. A dropped connection or 504 does not establish acceptance or rejection. Read/recovery calls SHOULD use bounded polling with backoff on transient failures; clients MUST stop at a terminal result or their local deadline. A deadline on polling does not cancel server work. This version has no negotiated polling interval or uniform Retry-After guarantee; defining one is open work.

The Mu profile defines durable submission IDs and the seven-day minimum receipt window separately from Micro-Id. Those semantics must not be generalized to every service operation.

9. Example

The following invokes Mu’s agent-discovery contract, not a mandatory core service. Content-Length is illustrative for the two-byte body, excluding any display newline.

POST / HTTP/1.1
Host: example.net
Micro-Protocol: mucp/1
Micro-Service: assistant
Micro-Endpoint: Assistant.ListAgents
Micro-Id: 12345678-1234-1234-1234-123456789abc
Authorization: Bearer <scoped-token>
Content-Type: application/json
Content-Length: 2

{}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-store
Micro-Protocol: mucp/1
Micro-Service: assistant
Micro-Endpoint: Assistant.ListAgents
Micro-Id: 12345678-1234-1234-1234-123456789abc

{"agents":[],"publicQuestions":false}

References

Normative dependencies: HTTP semantics, RFC 9110, JSON, RFC 8259, protobuf JSON mapping, bearer tokens, RFC 6750, and the versioned schema of the selected operation contract. Timestamp and binary representations follow the protobuf mapping’s referenced standards. The core’s Security and Privacy Considerations apply to this binding.

Licensed under Apache-2.0.