Files
skills/public/mcp_best_practices.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
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]>
2026-09-11 00:27:59 -07:00

325 lines
21 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>mcp_best_practices</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="/mcp_best_practices.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/mcp_best_practices">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/mcp_best_practices.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>mcp_best_practices</h1><p class="lede">Follow these standardized naming patterns:</p><h1>MCP Server Best Practices</h1>
<h2>Quick Reference</h2>
<h3>Server Naming</h3>
<ul><li><strong>Python</strong>: <code>{service}_mcp</code> (e.g., <code>slack_mcp</code>)</li><li><strong>Node/TypeScript</strong>: <code>{service}-mcp-server</code> (e.g., <code>slack-mcp-server</code>)</li></ul>
<h3>Tool Naming</h3>
<ul><li>Use snake_case with service prefix</li><li>Format: <code>{service}_{action}_{resource}</code></li><li>Example: <code>slack_send_message</code>, <code>github_create_issue</code></li></ul>
<h3>Response Formats</h3>
<ul><li>Support both JSON and Markdown formats</li><li>JSON for programmatic processing</li><li>Markdown for human readability</li></ul>
<h3>Pagination</h3>
<ul><li>Always respect <code>limit</code> parameter</li><li>Return <code>has_more</code>, <code>next_offset</code>, <code>total_count</code></li><li>Default to 20-50 items</li></ul>
<h3>Transport</h3>
<ul><li><strong>Streamable HTTP</strong>: For remote servers, multi-client scenarios</li><li><strong>stdio</strong>: For local integrations, command-line tools</li><li>Avoid SSE (deprecated in favor of streamable HTTP)</li></ul>
<hr>
<h2>Server Naming Conventions</h2>
<p>Follow these standardized naming patterns:</p>
<p><strong>Python</strong>: Use format <code>{service}_mcp</code> (lowercase with underscores)</p>
<ul><li>Examples: <code>slack_mcp</code>, <code>github_mcp</code>, <code>jira_mcp</code></li></ul>
<p><strong>Node/TypeScript</strong>: Use format <code>{service}-mcp-server</code> (lowercase with hyphens)</p>
<ul><li>Examples: <code>slack-mcp-server</code>, <code>github-mcp-server</code>, <code>jira-mcp-server</code></li></ul>
<p>The name should be general, descriptive of the service being integrated, easy to infer from the task description, and without version numbers.</p>
<hr>
<h2>Tool Naming and Design</h2>
<h3>Tool Naming</h3>
<ol><li><strong>Use snake_case</strong>: <code>search_users</code>, <code>create_project</code>, <code>get_channel_info</code></li><li><strong>Include service prefix</strong>: Anticipate that your MCP server may be used alongside other MCP servers</li></ol>
<ul><li>Use <code>slack_send_message</code> instead of just <code>send_message</code></li><li>Use <code>github_create_issue</code> instead of just <code>create_issue</code></li></ul>
<ol><li><strong>Be action-oriented</strong>: Start with verbs (get, list, search, create, etc.)</li><li><strong>Be specific</strong>: Avoid generic names that could conflict with other servers</li></ol>
<h3>Tool Design</h3>
<ul><li>Tool descriptions must narrowly and unambiguously describe functionality</li><li>Descriptions must precisely match actual functionality</li><li>Provide tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)</li><li>Keep tool operations focused and atomic</li></ul>
<hr>
<h2>Response Formats</h2>
<p>All tools that return data should support multiple formats:</p>
<h3>JSON Format (<code>response_format=&quot;json&quot;</code>)</h3>
<ul><li>Machine-readable structured data</li><li>Include all available fields and metadata</li><li>Consistent field names and types</li><li>Use for programmatic processing</li></ul>
<h3>Markdown Format (<code>response_format=&quot;markdown&quot;</code>, typically default)</h3>
<ul><li>Human-readable formatted text</li><li>Use headers, lists, and formatting for clarity</li><li>Convert timestamps to human-readable format</li><li>Show display names with IDs in parentheses</li><li>Omit verbose metadata</li></ul>
<hr>
<h2>Pagination</h2>
<p>For tools that list resources:</p>
<ul><li><strong>Always respect the <code>limit</code> parameter</strong></li><li><strong>Implement pagination</strong>: Use <code>offset</code> or cursor-based pagination</li><li><strong>Return pagination metadata</strong>: Include <code>has_more</code>, <code>next_offset</code>/<code>next_cursor</code>, <code>total_count</code></li><li><strong>Never load all results into memory</strong>: Especially important for large datasets</li><li><strong>Default to reasonable limits</strong>: 20-50 items is typical</li></ul>
<p>Example pagination response:</p>
<pre><code class="lang-json">{
&quot;total&quot;: 150,
&quot;count&quot;: 20,
&quot;offset&quot;: 0,
&quot;items&quot;: [...],
&quot;has_more&quot;: true,
&quot;next_offset&quot;: 20
}</code></pre>
<hr>
<h2>Transport Options</h2>
<h3>Streamable HTTP</h3>
<p><strong>Best for</strong>: Remote servers, web services, multi-client scenarios</p>
<p><strong>Characteristics</strong>:</p>
<ul><li>Bidirectional communication over HTTP</li><li>Supports multiple simultaneous clients</li><li>Can be deployed as a web service</li><li>Enables server-to-client notifications</li></ul>
<p><strong>Use when</strong>:</p>
<ul><li>Serving multiple clients simultaneously</li><li>Deploying as a cloud service</li><li>Integration with web applications</li></ul>
<h3>stdio</h3>
<p><strong>Best for</strong>: Local integrations, command-line tools</p>
<p><strong>Characteristics</strong>:</p>
<ul><li>Standard input/output stream communication</li><li>Simple setup, no network configuration needed</li><li>Runs as a subprocess of the client</li></ul>
<p><strong>Use when</strong>:</p>
<ul><li>Building tools for local development environments</li><li>Integrating with desktop applications</li><li>Single-user, single-session scenarios</li></ul>
<p><strong>Note</strong>: stdio servers should NOT log to stdout (use stderr for logging)</p>
<h3>Transport Selection</h3>
<p>| Criterion | stdio | Streamable HTTP | |-----------|-------|-----------------| | <strong>Deployment</strong> | Local | Remote | | <strong>Clients</strong> | Single | Multiple | | <strong>Complexity</strong> | Low | Medium | | <strong>Real-time</strong> | No | Yes |</p>
<hr>
<h2>Security Best Practices</h2>
<h3>Authentication and Authorization</h3>
<p><strong>OAuth 2.1</strong>:</p>
<ul><li>Use secure OAuth 2.1 with certificates from recognized authorities</li><li>Validate access tokens before processing requests</li><li>Only accept tokens specifically intended for your server</li></ul>
<p><strong>API Keys</strong>:</p>
<ul><li>Store API keys in environment variables, never in code</li><li>Validate keys on server startup</li><li>Provide clear error messages when authentication fails</li></ul>
<h3>Input Validation</h3>
<ul><li>Sanitize file paths to prevent directory traversal</li><li>Validate URLs and external identifiers</li><li>Check parameter sizes and ranges</li><li>Prevent command injection in system calls</li><li>Use schema validation (Pydantic/Zod) for all inputs</li></ul>
<h3>Error Handling</h3>
<ul><li>Don&#x27;t expose internal errors to clients</li><li>Log security-relevant errors server-side</li><li>Provide helpful but not revealing error messages</li><li>Clean up resources after errors</li></ul>
<h3>DNS Rebinding Protection</h3>
<p>For streamable HTTP servers running locally:</p>
<ul><li>Enable DNS rebinding protection</li><li>Validate the <code>Origin</code> header on all incoming connections</li><li>Bind to <code>127.0.0.1</code> rather than <code>0.0.0.0</code></li></ul>
<hr>
<h2>Tool Annotations</h2>
<p>Provide annotations to help clients understand tool behavior:</p>
<p>| Annotation | Type | Default | Description | |-----------|------|---------|-------------| | <code>readOnlyHint</code> | boolean | false | Tool does not modify its environment | | <code>destructiveHint</code> | boolean | true | Tool may perform destructive updates | | <code>idempotentHint</code> | boolean | false | Repeated calls with same args have no additional effect | | <code>openWorldHint</code> | boolean | true | Tool interacts with external entities |</p>
<p><strong>Important</strong>: Annotations are hints, not security guarantees. Clients should not make security-critical decisions based solely on annotations.</p>
<hr>
<h2>Error Handling</h2>
<ul><li>Use standard JSON-RPC error codes</li><li>Report tool errors within result objects (not protocol-level errors)</li><li>Provide helpful, specific error messages with suggested next steps</li><li>Don&#x27;t expose internal implementation details</li><li>Clean up resources properly on errors</li></ul>
<p>Example error handling:</p>
<pre><code class="lang-typescript">try {
const result = performOperation();
return { content: [{ type: &quot;text&quot;, text: result }] };
} catch (error) {
return {
isError: true,
content: [{
type: &quot;text&quot;,
text: `Error: ${error.message}. Try using filter=&#x27;active_only&#x27; to reduce results.`
}]
};
}</code></pre>
<hr>
<h2>Testing Requirements</h2>
<p>Comprehensive testing should cover:</p>
<ul><li><strong>Functional testing</strong>: Verify correct execution with valid/invalid inputs</li><li><strong>Integration testing</strong>: Test interaction with external systems</li><li><strong>Security testing</strong>: Validate auth, input sanitization, rate limiting</li><li><strong>Performance testing</strong>: Check behavior under load, timeouts</li><li><strong>Error handling</strong>: Ensure proper error reporting and cleanup</li></ul>
<hr>
<h2>Documentation Requirements</h2>
<ul><li>Provide clear documentation of all tools and capabilities</li><li>Include working examples (at least 3 per major feature)</li><li>Document security considerations</li><li>Specify required permissions and access levels</li><li>Document rate limits and performance characteristics</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="/mcp_best_practices.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>