mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
300 lines
24 KiB
HTML
300 lines
24 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0300</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0300.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0300">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0300.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0300</h1><p class="lede">HIP-300: Unified MCP — one endpoint, and local servers that forward to it. Status Final. Hanzo architectural specification.</p><h1>HIP-0300: Unified MCP — one endpoint, and local servers that forward to it</h1>
|
|
<h2>Abstract</h2>
|
|
<p>Hanzo has one tool surface for models, and it is the cloud's: <code>POST /v1/mcp</code> on the deployment's API host, projected from the same typed-op registry that yields the REST routes and the OpenAPI document. Every local MCP server Hanzo ships — <code>@hanzo/mcp</code> (TypeScript), <code>hanzo-mcp</code> (Python), <code>hanzo-mcp</code> (Rust) — carries the tools that need the machine it runs on, and reaches the cloud by forwarding <code>tools/list</code> and <code>tools/call</code> to that endpoint. Nothing about the cloud is written down in a local server, in any language, ever again.</p>
|
|
<p>This document replaces the one deleted on 2026-07-28, which mandated a tool set its own status section contradicted. Every number here was measured against the named artifact on 2026-08-20; re-measure before quoting one.</p>
|
|
<h2>Motivation</h2>
|
|
<p>Three things went wrong in the same direction, and all three are one mistake:</p>
|
|
<ul><li>The endpoint projected every typed operation as its own tool: 1,189 tools in</li></ul>
|
|
<p> 977 KB, which no model holds and every client truncates (Slack keeps 128).</p>
|
|
<ul><li>The local servers each hand-rolled their own cloud tools against the REST</li></ul>
|
|
<p> API: 1,051 lines in TypeScript, 1,017 in Rust, a runtime-fetched OpenAPI catalogue in Python — three clients of one API, each at its own version of it, one of them still calling an <code>/api/</code> prefix the API has not served in months.</p>
|
|
<ul><li>A fourth approach was in flight: generate a per-language catalogue of 2,279</li></ul>
|
|
<p> flat tools from the document and ship it inside each package — a static copy of what the endpoint computes live and curates.</p>
|
|
<p>The mistake is a second description of the cloud's tool surface anywhere but the cloud. The cloud already knows what it serves; a local server asks it.</p>
|
|
<h2>Specification</h2>
|
|
<p>The key words MUST, MUST NOT, SHOULD and MAY are as in RFC 2119.</p>
|
|
<h3>§1 The endpoint</h3>
|
|
<ol><li>The endpoint is <code>POST /v1/mcp</code> on the deployment's API host (<code>api.hanzo.ai</code>,</li></ol>
|
|
<p> <code>api.lux.cloud</code>, …). It speaks JSON-RPC 2.0, one POST per message, stateless; protocol revision <code>2026-07-28</code>. The framework default <code>/mcp</code> answers 308 to it. The address is stated once (<code>manifest/door.Path</code>) and read by the host that serves it, the document that describes it and the console that refuses to answer it with HTML.</p>
|
|
<ol><li>The endpoint MUST be described in the API document as an operation</li></ol>
|
|
<p> (<code>POST /v1/mcp</code>, with the JSON-RPC envelope as its bodies), so every projection of the document — SDKs, CLI, docs — names it.</p>
|
|
<ol><li><code>tools/list</code> MUST answer without a credential. It answers **one tool per</li></ol>
|
|
<p> subsystem** plus <code>describe</code>. A subsystem tool is named for the subsystem (<code>agents</code>, <code>billing</code>, <code>git</code>) and takes <code>{"op": <operation>, "input": {}}</code>, where <code>op</code> is an enum of the operations that subsystem publishes, spelled as verb phrases (<code>deploy_project</code>, not <code>post_v1_projects_by_slug_deploy</code>). <code>describe</code> takes <code>{"op"}</code> and returns that operation's input schema; it is listed first so a truncating client keeps it. Measured: 1,671 public paths project as 110 tools in 81 KB.</p>
|
|
<ol><li>The tool surface IS the public contract. An operation is offered when it is</li></ol>
|
|
<p> typed (dispatchable by its subsystem, <code>x-tool</code>) AND public (<code>x-public</code> — every <code>/v1</code> operation except the operator's <code>admin</code> product, relay endpoints and legacy spellings). An operation whose name discloses a bearer secret at any verb, or mutates an identity or authority object, is withheld; <code>result._meta</code> carries the count and the rule (<code>hanzo.ai/refused</code>), and the subsystems that did not answer (<code>hanzo.ai/unavailable</code>). A shortened list MUST say so.</p>
|
|
<ol><li>A subsystem tool whose every offered operation is a read carries</li></ol>
|
|
<p> <code>annotations.readOnlyHint: true</code>; one that mixes reads and writes carries no hint. <code>describe</code> is read-only.</p>
|
|
<ol><li><code>tools/call</code> takes the same bearer the REST API does. The endpoint validates</li></ol>
|
|
<p> nothing: the request is forwarded to the owning subsystem, whose identity boundary derives the principal and refuses on its own terms. A <code>tools/call</code> that reaches the public endpoint with no credential (no <code>Authorization</code>, no <code>X-Authorization</code>, no cookie) MUST be answered <strong>HTTP 401</strong> with <code>WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"</code> (RFC 9728 §5.1). The plane-side endpoint the fleet's own subsystems reach is never challenged: a sibling's identity is the headers the socket vouches for.</p>
|
|
<ol><li>The host MUST serve <code>GET /.well-known/oauth-protected-resource</code> (and the</li></ol>
|
|
<p> <code>/v1/mcp</code>-suffixed form) naming the deployment's IAM issuer as the authorization server, so an MCP client can obtain a bearer through the standard OAuth flow against <code>hanzo.id</code> (HIP-0111). The resource is the origin the client reached.</p>
|
|
<h3>§2 Local servers</h3>
|
|
<ol><li>A local server ships the tools that need the machine: <code>fs</code>, <code>exec</code>, <code>git</code>,</li></ol>
|
|
<p> <code>code</code>, <code>fetch</code>, <code>workspace</code>, <code>ui</code>, and the optional <code>think</code>, <code>memory</code>, <code>plan</code>, <code>tasks</code>, <code>mode</code>. These need no account.</p>
|
|
<ol><li>A local server MUST NOT implement a cloud operation itself, generate a</li></ol>
|
|
<p> catalogue of them, or describe them in any form. It reaches the cloud by forwarding:</p>
|
|
<ul><li>the endpoint address is <code>HANZO_MCP_DOOR</code>, else `<HANZO_API_BASE or</li></ul>
|
|
<p> https://api.hanzo.ai>/v1/mcp`;</p>
|
|
<ul><li>the bearer is <code>HANZO_API_KEY</code> (and the server's existing fallbacks), else</li></ul>
|
|
<p> <code>hanzo auth token</code>;</p>
|
|
<ul><li><code>tools/list</code> = the local tools, then the endpoint's tools whose names are not</li></ul>
|
|
<p> already local — <strong>a local name wins</strong> (<code>git</code> collides, and the local <code>git</code> is the one the machine has);</p>
|
|
<ul><li><code>tools/call</code> = a local tool by name, else the caller's call forwarded to the</li></ul>
|
|
<p> endpoint verbatim, the endpoint's <code>result</code> returned verbatim, <code>isError</code> included;</p>
|
|
<ul><li>a 401 from the endpoint becomes an <code>isError</code> result telling the caller to sign</li></ul>
|
|
<p> in (<code>hanzo auth login</code>) and naming the resource metadata URL;</p>
|
|
<ul><li>the endpoint's list is cached briefly (order of minutes) and an endpoint that does</li></ul>
|
|
<p> not answer costs one line on stderr and a local-only list — never a failed start. <code>hanzo-mcp</code> is spawned by <code>dev</code>; a hang is a dead agent.</p>
|
|
<ol><li>A local server's own protocol revision is what it implements; it MUST NOT</li></ol>
|
|
<p> advertise the endpoint's.</p>
|
|
<ol><li>The three servers are peers, not ports: each is native to its language and</li></ol>
|
|
<p> they share the contract above, not code. The <code>go/</code> REST shim that once mounted <code>/v1/mcp/tools/:name</code> is retired; the cloud's endpoint owns <code>/v1/mcp</code>.</p>
|
|
<p>First versions carrying this: <code>@hanzo/mcp</code> 2.4.8, <code>hanzo-mcp</code> (PyPI) 0.15.16, <code>hanzo-mcp</code> (crates) 1.1.24.</p>
|
|
<h3>§3 Clients</h3>
|
|
<p>An MCP client (Claude Code, Cursor, Claude Desktop, Codex, <code>dev</code>) connects in one of two shapes, and both are one server name:</p>
|
|
<pre><code class="lang-jsonc">// the local server, which forwards — works for every client, stdio
|
|
{ "mcpServers": { "hanzo": { "command": "npx", "args": ["-y", "--package=@hanzo/mcp", "hanzo-mcp", "serve"] } } }
|
|
|
|
// the endpoint directly — for clients that speak streamable HTTP
|
|
{ "mcpServers": { "hanzo": { "type": "http", "url": "https://api.hanzo.ai/v1/mcp" } } }</code></pre>
|
|
<p><code>dev</code> ships <code>@hanzo/mcp</code> and launches the first; it MAY add the second.</p>
|
|
<h3>§4 Conformance</h3>
|
|
<ul><li><code>cloud</code>: <code>fleet/grouped_test.go</code> (one tool per subsystem, under the client</li></ul>
|
|
<p> cap), <code>fleet/challenge_test.go</code> (401 at the edge, never on the plane), <code>fleet/catalog_test.go</code> (the catalogue equals the documents), <code>cmd/cloud/oauth_test.go</code> (the metadata names the issuer), <code>openapi/public_test.go</code> (the endpoint is in the document and public), <code>e2e/mcp-door.sh</code> (zero wakes on list, one on call, no empty description).</p>
|
|
<ul><li>each local server: a test against a fake endpoint — list merge with local</li></ul>
|
|
<p> winning, call forwarded verbatim, 401 → sign-in error, endpoint down → local-only.</p>
|
|
<ul><li>the release: the <code>reach</code> car fails when any subsystem is in</li></ul>
|
|
<p> <code>_meta["hanzo.ai/unavailable"]</code>.</p>
|
|
<h2>Rationale</h2>
|
|
<p><strong>One description.</strong> The endpoint is a projection of the registry that already describes every operation; a second description in a local server is the drift this document's predecessor died of. Forwarding makes the local servers correct by construction and current at the instant of the call.</p>
|
|
<p><strong>One tool per subsystem.</strong> A model pays context for every tool it is shown. A subsystem is the grain a person reasons at ("ask billing"), and <code>describe</code> makes the enum usable without carrying every schema.</p>
|
|
<p><strong>Local wins.</strong> The machine's own <code>git</code> is the one the user means when the server runs beside a checkout; the cloud's is one <code>describe</code> away.</p>
|
|
<p><strong>Challenge, do not validate.</strong> The endpoint stays a router: it knows absence, not validity. Validity is the owning subsystem's, where the identity boundary already is.</p>
|
|
<h2>Security Considerations</h2>
|
|
<p>The endpoint offers the public contract and nothing beside it; the operator's surface is neither an SDK method nor a tool a model is shown. Names that would disclose a secret or mutate an identity are withheld before the routing table is written, so a client that cached such a name gets the same answer as for a tool that never existed. Bearers travel only in <code>Authorization</code>; a local server never writes one to disk and never echoes one in a result.</p>
|
|
<h2>References</h2>
|
|
<ul><li>HIP-0010 MCP Integration · HIP-0106 Plugin Contract · HIP-0111 IAM</li></ul>
|
|
<p> Authentication · HIP-0128 Resource Surface</p>
|
|
<ul><li><code>hanzoai/cloud</code> <code>fleet/</code>, <code>manifest/door</code>, <code>cmd/cloud/oauth.go</code>,</li></ul>
|
|
<p> <code>openapi/mcp.go</code>, <code>openapi/public.go</code></p>
|
|
<ul><li><code>hanzoai/mcp</code> <code>src/door.ts</code>, <code>rust/src/door.rs</code>;</li></ul>
|
|
<p> <code>hanzoai/python-sdk</code> <code>pkg/hanzo-mcp/hanzo_mcp/door.py</code></p>
|
|
<ul><li>RFC 9728 OAuth 2.0 Protected Resource Metadata</li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0300.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |