Authorization

Based on Model Context Protocol Revision: 2025‑03‑26

This guide describes how Hyperia servers and clients implement secure, interoperable OAuth 2.1‑based authorization for HTTP‑family transports. STDIO deployments typically pull creds from the environment; HTTP deployments should follow this spec.

---

1 · Purpose & Scope

The Model Context Protocol (MCP) supports locking down endpoints so only authorised clients can act on behalf of resource owners. This section standardises the flow for HTTP‑based transports.

Transport	Requirement
HTTP / Streamable HTTP	SHOULD implement this spec
STDIO	SHOULD NOT – read creds from env/CLI
Other (WebSocket, gRPC …)	MUST follow best practices for that protocol

---

2 · Standards Foundation

Hyperia narrows OAuth to a secure, interoperable subset:

• OAuth 2.1 draft – core flows

• RFC 8414 – Authorization Server Metadata Discovery

• RFC 7591 – Dynamic Client Registration

PKCE is mandatory; implicit flow is forbidden.

---

3 · Authorization Flow (High Level)

1. Client hits protected MCP endpoint → server responds 401.

2. Client discovers metadata (/.well‑known/oauth-authorization-server).

3. Optional ‑ Client registers via RFC 7591.

4. Client performs OAuth flow (Auth Code + PKCE or Client Creds).

5. Client retries MCP call with Authorization: Bearer <token>.

Recommended Grant Types

Flow	When
Auth Code + PKCE	End‑user present; SaaS scenarios
Client Credentials	App‑to‑app machine calls

Sequence (Auth Code)

sequenceDiagram
    participant B as Browser
    participant C as MCP Client
    participant S as Hyperia Server

    C->>S: MCP request (no token)
    S-->>C: 401 Unauthorized
    C->>S: GET /.well-known/oauth-authorization-server
    S-->>C: Metadata or 404
    C->>B: Open auth URL+PKCE
    B->>S: /authorize…
    S-->>B: Redirect → app with code
    B-->>C: code
    C->>S: POST /token (code+verifier)
    S-->>C: Access/Refresh token
    C->>S: MCP request (Bearer token)

---

4 · Server Metadata Discovery

Clients MUST attempt RFC 8414 discovery first; servers SHOULD serve metadata. If /​.well-known/oauth-authorization-server returns 404, clients fall back to default paths:

Endpoint	Default	Example (api.example.com/v1/mcp)
Authorization	/authorize	https://api.example.com/authorize
Token	/token	https://api.example.com/token
Registration	/register	https://api.example.com/register

Clients should include header MCP-Protocol-Version: 2025-03-26 during discovery.

Deriving Base URL

Strip the path of the MCP endpoint. Eg. https://api.example.com/v1/mcp → base https://api.example.com.

---

5 · Dynamic Client Registration

Hyperia servers SHOULD accept RFC 7591 /register so unknown clients can obtain a client_id without UX friction. If not supported, servers must document manual registration.

---

6 · Access‑Token Usage

• Always send Authorization: Bearer … header.

• Never place tokens in query strings.

• Servers validate per OAuth 2.1 §5; invalid → 401.

Example:

GET /v1/tools HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

---

7 · Security Requirements

1. HTTPS only.

2. PKCE required for public clients.

3. Token rotation SHOULD be enabled.

4. Redirect URIs must be HTTPS or localhost.

5. Servers validate scopes and expiry.

Error Codes

Code	Meaning
401	No/invalid token
403	Token lacks scope
400	Malformed request

---

8 · Third‑Party Authorization (Optional)

Hyperia may delegate to an external OAuth server:

sequenceDiagram
    participant C as MCP Client
    participant H as Hyperia Server
    participant T as Third‑Party Auth
    C->>H: /authorize
    H->>C: Redirect → T
    C->>T: Auth
    T->>H: code
    H->>T: /token
    T-->>H: access_token
    H->>C: Continue OAuth

Servers must bind Hyperia tokens to the underlying third‑party session and re‑validate on each call.

---

9 · Best Practices

• Local desktop clients = public OAuth 2.1 apps with PKCE.

• Implement metadata discovery to avoid hard‑coding endpoints.

• Use Dynamic Client Registration where possible.

• Store refresh/access tokens securely (OS keychain, sealed secrets).