Skip to content

Discovery and RFC Map

Jump to bottom
jmrGrav edited this page Aug 22, 2026 · 2 revisions

Discovery and RFC Map

This page maps public discovery endpoints to the standards and client behaviors they support.

Core Endpoints

Endpoint Purpose
https://mcp.arleo.eu/mcp MCP Streamable HTTP JSON-RPC endpoint
https://mcp.arleo.eu/.well-known/oauth-authorization-server OAuth Authorization Server Metadata
https://mcp.arleo.eu/.well-known/oauth-protected-resource OAuth Protected Resource Metadata
https://mcp.arleo.eu/.well-known/oauth-protected-resource/mcp Protected resource alias for /mcp clients
https://mcp.arleo.eu/.well-known/mcp/server-card.json MCP server card
https://mcp.arleo.eu/.well-known/mcp.json Compatibility alias for server card
https://www.arleo.eu/auth.md Public agent auth guide consumed by AgentReady scanners
https://mcp.arleo.eu/auth.md MCP-hosted auth guide
https://www.arleo.eu/llms.txt LLM discovery
https://www.arleo.eu/robots.txt Crawler access policy
https://mcp.arleo.eu/openapi.json OpenAPI 3.1.0 document (OAuth/discovery endpoints only — the MCP tool catalog is dynamic, tools/list over /mcp is the source of truth, not enumerated here)
https://mcp.arleo.eu/health Liveness probe

OAuth Metadata Invariants

Authorization server metadata should expose:

issuer
authorization_endpoint
token_endpoint
registration_endpoint
scopes_supported
response_types_supported
grant_types_supported
code_challenge_methods_supported
token_endpoint_auth_methods_supported

Protected resource metadata should expose:

resource
authorization_servers
bearer_methods_supported
scopes_supported

Expected values:

issuer = https://mcp.arleo.eu
authorization_servers includes https://mcp.arleo.eu

resource is host-dependent as of 2026-08-22 — do not hardcode a single expected value. buildProtectedResourceMeta (internal/server/discovery.go) reflects the queried Host into resource only when it exactly matches cfg.SiteURL's hostname (www.arleo.eu); every other host, including the issuer's own, gets the unmodified configured/default value:

GET https://mcp.arleo.eu/.well-known/oauth-protected-resource            -> resource = https://mcp.arleo.eu/mcp
GET https://www.arleo.eu/.well-known/oauth-protected-resource            -> resource = https://www.arleo.eu
GET https://www.arleo.eu/.well-known/oauth-protected-resource/mcp        -> resource = https://mcp.arleo.eu/mcp  (alias never varies by host — RFC 9728 §3.1 fixes its resource identity to <issuer>/mcp)
GET https://mcp.arleo.eu/.well-known/oauth-protected-resource/mcp        -> resource = https://mcp.arleo.eu/mcp

Why this exists: an earlier fix replaced www.arleo.eu's hardcoded static JSON file with a 308 redirect to mcp.arleo.eu. That silently broke isitagentready.com's scan — several RFC 9728 validators check resource against the origin they actually queried, and a redirect always serves the issuer's own resource regardless of which host was asked. The fix was to reverse-proxy (not redirect) www.arleo.eu straight to the Go server and make the handler itself host-aware, rather than trying to keep two static copies in sync. If you ever see this regress again, check Host propagation between Cloudflare → OpenResty → the Go server first — curl -s https://www.arleo.eu/.well-known/oauth-protected-resource | grep resource should show https://www.arleo.eu, not mcp.arleo.eu/mcp.

AgentReady Auth.md Invariants

auth.md must contain human-readable guidance and machine-readable registration metadata.

Required machine-readable concepts:

  • registration_endpoint
  • authorization_endpoint
  • token_endpoint
  • MCP endpoint
  • canonical scopes
  • agent registration flow
  • agent_auth_metadata
  • identity_assertion
  • ID-JAG token type
  • credential_types_supported

As of 2026-08-22, /register's and /token's "returns" field lists inside auth.md are self-correcting, not just hand-typed: handleAuthMd rewrites those two JSON arrays in-place via reflection over oauth.RegistrationResponse/oauth.TokenResponse before serving, regardless of what the source markdown says. That closed a real drift (a stale client_secret claim, a missing scope field on /token) that a live audit caught. www.arleo.eu/auth.md and mcp.arleo.eu/auth.md both proxy to the Go server now (previously www served Hugo's static copy directly), so they can no longer disagree on these two fields. Everything else in auth.md — prose, other endpoints, examples — is still served verbatim from the source file, unenforced.

Standards Checklist

Area Expected support
OAuth 2.0 Authorization Code
PKCE S256
Bearer tokens Authorization: Bearer header
OAuth metadata RFC 8414 style authorization server metadata
Protected resource metadata RFC 9728 style metadata
Dynamic Client Registration /register, bounded by policy
MCP Streamable HTTP transport at /mcp
Server card canonical /.well-known/mcp/server-card.json plus compatibility alias

Quick Verification

curl -sk https://mcp.arleo.eu/.well-known/oauth-authorization-server | jq .
curl -sk https://mcp.arleo.eu/.well-known/oauth-protected-resource | jq .
curl -sk https://mcp.arleo.eu/.well-known/oauth-protected-resource/mcp | jq .
curl -sk https://mcp.arleo.eu/.well-known/mcp/server-card.json | jq .
curl -sk https://www.arleo.eu/auth.md | grep -E 'registration_endpoint|agent_auth_metadata|credential_types_supported'
curl -sk https://www.arleo.eu/.well-known/oauth-protected-resource | jq -r .resource   # expect https://www.arleo.eu
curl -sk https://mcp.arleo.eu/openapi.json | jq -r .openapi                            # expect 3.1.0
curl -sk https://mcp.arleo.eu/health | jq .

If any required endpoint returns 404, first check the host routing and reverse proxy before changing protocol code.

Clone this wiki locally