Xpersona
Claim this agent
agentCLAWHUBUnverified

mcp-best-practices

Build, harden, and debug production MCP servers with the TypeScript SDK. Use when writing or reviewing an MCP server - transports, tool schemas, errors, OAuth, token bloat, SDK migrations, MCP Apps, Registry. Assumes a server already exists.

OpenClaw
View on ClawHubHomepage

Rank

62

Safety

84

Downloads

2.4k

Updated

Oct 9, 2026

Version

1.3.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 2.4K downloads reported by the source. Last updated 10/9/2026.

Avoid when

  • Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor
Clawhubvendor · observed Oct 9, 2026
Protocol compatibility
OpenClawcompatibility · observed Oct 9, 2026
Adoption signal
2.4K downloadsadoption · observed Oct 9, 2026
Latest release
1.3.0release · observed Oct 6, 2026
Handshake status
UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17bp3v1hm1dnkzey0c9tfh02183j0y5:mcp-best-practices
  1. Install using `clawhub skill install s17bp3v1hm1dnkzey0c9tfh02183j0y5:mcp-best-practices` in an isolated environment before connecting it to live workloads.
  2. No published capability contract is available yet, so validate auth and request/response behavior manually.
  3. Review the upstream CLAWHUB listing at https://clawhub.ai/tenequm/mcp-best-practices before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-tenequm-mcp-best-practices/snapshot"

Documentation

CLAWHUB

150,739 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: mcp-best-practices
description: Build, harden, and debug production MCP servers with the TypeScript SDK. Use when writing or reviewing an MCP server - transports, tool schemas, errors, OAuth, token bloat, SDK migrations, MCP Apps, Registry. Assumes a server already exists.
metadata:
  version: "1.3.0"
  categories: "development, integrations"
  topics: "mcp, typescript-sdk, tool-design, transports, server-hardening"
  upstream: "@modelcontextprotocol/[email protected], @modelcontextprotocol/[email protected], @modelcontextprotocol/[email protected], modelcontextprotocol-spec@2026-07-28"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/mcp-best-practices
    emoji: "🔌"
    envVars:
      - name: MAX_MCP_OUTPUT_TOKENS
        required: false
        description: Claude Code client-side cap on MCP tool result size, referenced in the result-size budget guidance
---

# MCP Best Practices

Decision reference for building production MCP servers with the TypeScript SDK. Not a tutorial - assumes you already have a working server and need to make it correct, fast, and secure.

## Quick Reference

| Component | Current | Notes |
|-----------|---------|-------|
| Spec (released) | **2026-07-28** ([specification](https://modelcontextprotocol.io/specification/latest)) | Stateless/sessionless overhaul - see "Spec 2026-07-28" below and `references/spec-2026-07-28.md` |
| Spec (still deployed) | **2025-11-25** | Still the bulk of deployed software and the TS client default - but Claude Code now negotiates 2026-07-28 with HTTP servers that offer it |
| TS SDK (current) | **v2.3.1** (2026-10-05): `/server`, `/client`, `/core` 2.3.1; `/node` 2.1.1, `/express` + `/hono` 2.0.2, `/fastify` 2.0.1 (no longer lockstep) | `createMcpHandler` serves both eras by default; the client speaks 2025-era unless told otherwise |
| TS SDK (legacy) | **v1.32.1** (`@modelcontextprotocol/sdk`) | Bug + security fixes for >=6 months after v2 GA, never a revision past 2025-11-25; source on the [`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x) |
| JSON Schema | **2020-12** default (2019-09 / draft-07 accepted since v2.0.0) | - |
| Transport | **Streamable HTTP** (remote), **stdio** (local) | SSE + WebSocket removed in v2 |
| Extensions | **MCP Apps** (Stable, SEP-1865), **Auth Extensions** (official), **Tasks** ([ext-tasks](https://github.com/modelcontextprotocol/ext-tasks)) | Domain-specific WGs |
| Registry | **Preview** with v0.1 API freeze since 2025-10-24 ([registry](https://modelcontextprotocol.io/registry/about)) | GA pending |

**v2 imports** (current):
```typescript
import { McpServer } from "@modelcontextprotocol/server";
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/server";
import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/core";
```

**v1 imports** (legacy line, still widely deployed):
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

_meta.json

{
  "ownerId": "kn76gpsgjw5chv0xvzbzcb8cxn81x46r",
  "slug": "mcp-best-practices",
  "version": "1.3.0",
  "publishedAt": 1791289113750
}

references/error-handling.md

# Error Handling

Full error taxonomy, code examples, and patterns for tool errors, protocol errors, and payment integration.

## Table of Contents
- [Error Taxonomy](#error-taxonomy)
- [Tool Execution Errors](#tool-execution-errors)
- [Protocol Errors](#protocol-errors)
- [The error.data Loss Bug](#the-errordata-loss-bug)
- [Error Helper Pattern](#error-helper-pattern)
- [Payment Error Patterns](#payment-error-patterns)

## Error Taxonomy

MCP has two distinct error reporting mechanisms. Choosing the wrong one makes the LLM blind to fixable problems.

| Type | JSON-RPC | LLM Visibility | Self-Correction | Use For |
|------|----------|----------------|-----------------|---------|
| **Tool Execution Error** | `CallToolResult` with `isError: true` | Always (clients SHOULD show) | Yes | Input validation, API failures, business logic, rate limits |
| **Protocol Error** | JSON-RPC error response (`{ error: { code, message } }`) | Maybe (clients MAY show) | No | Unknown tool, malformed request, server crash, capability mismatch |

**The rule** (SEP-1303, merged into spec 2025-11-25): If the LLM could self-correct by seeing the error message, it MUST be a Tool Execution Error. Protocol errors are for structural problems the LLM can't fix.

### SEP-2140 Extension (proposal; issue closed in favor of spec PR #2145)

Extends SEP-1303 to cover three more cases that should also be Tool Execution Errors:
1. **Tool resolution failures** - unknown tool name (currently protocol error)
2. **Tool unavailability** - disabled/policy-restricted tool
3. **Output validation failures** - structuredContent doesn't match outputSchema

Source: [modelcontextprotocol#2140](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2140), closed 2026-01-23 in favor of [PR #2145](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2145)

## Tool Execution Errors

Return `isError: true` in the `CallToolResult`. The content array carries the error message the LLM will see.

### Input Validation

```typescript
async function searchHandler({ query, since }: { query: string; since?: string }) {
  // Validate input - return tool error so LLM can correct
  if (since) {
    const date = new Date(since);
    if (isNaN(date.getTime())) {
      return {
        isError: true,
        content: [{ type: "text", text: `Invalid date format: "${since}". Use ISO format (YYYY-MM-DD).` }],
      };
    }
    if (date > new Date()) {
      return {
        isError: true,
        content: [{ type: "text", text: `Date must be in the past. Received: ${since}. Current: ${new Date().toISOString().split("T")[0]}` }],
      };
    }
  }

  const results = await doSearch(query, since);
  return { content: [{ type: "text", text: JSON.stringify(results) }] };
}
```

### Upstream API Failures

```typescript
async function fetchHandler({ url }: { url: string }) {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      return {
        isError: true,
        content:

references/extensions-registry.md

# Extensions and Registry

MCP extensions system, authorization extensions, and the MCP Registry.

## Table of Contents
- [Extensions System](#extensions-system)
- [Authorization Extensions](#authorization-extensions)
- [MCP Registry](#mcp-registry)
- [Server Capabilities Beyond Tools](#server-capabilities-beyond-tools)

## Extensions System

Extensions are optional, strictly additive capabilities layered on the core MCP protocol. They enable modular features (auth), specialized behavior (domain-specific), and experimental incubation without changing the core spec.

### Three-Layer Architecture

1. **MCP Core Specification** - baseline client-server interoperability
2. **MCP Projects** - supporting infrastructure (Registry, Inspector)
3. **MCP Extensions** - optional patterns for specialized use cases

### Extension Identifiers

Format: `{vendor-prefix}/{extension-name}`

| Prefix | Usage |
|--------|-------|
| `io.modelcontextprotocol` | Official extensions |
| Reversed domain (e.g., `com.example`) | Third-party extensions |

### Official Extensions

| Extension | Identifier | Status | Repo |
|-----------|-----------|--------|------|
| MCP Apps | `io.modelcontextprotocol/ui` | Stable (SEP-1865, 2026-01-26); SDK `[email protected]` 2026-09-08 | [ext-apps](https://github.com/modelcontextprotocol/ext-apps) |
| OAuth Client Credentials | `io.modelcontextprotocol/oauth-client-credentials` | Draft | [ext-auth](https://github.com/modelcontextprotocol/ext-auth) |
| Enterprise-Managed Auth | `io.modelcontextprotocol/enterprise-managed-authorization` | Stable (2026-06-18) | [ext-auth](https://github.com/modelcontextprotocol/ext-auth) |
| Tasks | `io.modelcontextprotocol/tasks` | Official (SEP-2663, final 2026-05-15); repo dropped its "experimental" framing 2026-08-19, schema frozen Stable at `2026-07-28` | [ext-tasks](https://github.com/modelcontextprotocol/ext-tasks) |
| Skills | `io.modelcontextprotocol/skills` | Official ([SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension) Final; merged 2026-09-13) | [docs](https://modelcontextprotocol.io/extensions/skills/overview) |

### Negotiation

**2025-era wires** - both sides declare extension support in `extensions` during initialization:

```json
// Client (initialize request)
{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/ui": { "mimeTypes": ["text/html;profile=mcp-app"] }
    }
  }
}

// Server (initialize response)
{
  "capabilities": {
    "extensions": { "io.modelcontextprotocol/ui": {} }
  }
}
```

**On 2026-07-28** there is no `initialize`, so this exchange does not exist. Clients advertise extension support **per request**:

> Clients advertise extension support in `_meta["io.modelcontextprotocol/clientCapabilities"]` within each request

Servers advertise theirs in the `capabilities` of their `server/discover` result. The `extensions` field was added to both `ClientCapabilities` and `ServerCapabilities` in this revision.

Each extension defines its settings s

references/mcp-apps.md

# MCP Apps

Interactive HTML interfaces rendered inside MCP hosts. The MCP Apps spec (SEP-1865) reached **Stable** status on 2026-01-26 as the first official MCP extension (`io.modelcontextprotocol/ui`).

> **`@modelcontextprotocol/ext-apps` 2.0.0 (2026-09-08; current 2.0.3, whose published `dist/` is unchanged) is a breaking release - of the TypeScript API, not the protocol.** *"The MCP Apps wire protocol is unchanged: 2.x Views run in 1.x hosts and 2.x hosts render 1.x Views (covered by a test that runs the published 1.7.5 against this release in both directions). What breaks is dependencies and the TypeScript API."* You can upgrade either side independently. See [Migrating to 2.0](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/migrate-to-2.md).

## Upgrading to ext-apps 2.0

| Change | Detail |
|---|---|
| **Peer packages** | `@modelcontextprotocol/sdk@^1` is replaced by `@modelcontextprotocol/client@^2.0.0` and `@modelcontextprotocol/core@^2.0.0` (both **required** - `App` and `AppBridge` extend the client's `Protocol`) and `@modelcontextprotocol/server@^2.0.0` (optional, only for the `./server` helpers). Node.js 20+. |
| **Zod** | **zod 3 is dropped**; the peer range is `zod@^4.2.0`. Schemas must implement Standard JSON Schema (`~standard.jsonSchema`) - *"zod 4.0 and 4.1 do not expose `~standard.jsonSchema`"*, so 4.2.0 is a real floor, not a suggestion. ArkType and Valibot also qualify. |
| **Handler context** | *"Custom handlers receive the SDK 2.x `BaseContext`: `extra.signal` is now `extra.mcpReq.signal`, `extra.requestId` is `extra.mcpReq.id`."* |
| **Registration** | The 1.x `(Schema, handler)` form *"still works as a deprecated overload with a one-time warning ... and goes away in 3.0."* Move to the config-object form now. |

The examples below use the v1-era imports (`@modelcontextprotocol/sdk/...`), which remain correct on the 1.x line. On 2.x, import `McpServer` and the transport from `@modelcontextprotocol/server` exactly as in `v2-migration.md`, and install `@modelcontextprotocol/ext-apps @modelcontextprotocol/server @modelcontextprotocol/client @modelcontextprotocol/core zod@^4.2.0` instead of the 1.x pair.

## Table of Contents
- [Architecture](#architecture)
- [Server Implementation](#server-implementation)
- [UI Implementation](#ui-implementation)
- [Project Setup](#project-setup)
- [CSP and Security](#csp-and-security)
- [Testing](#testing)
- [When to Use](#when-to-use)
- [Client Support](#client-support)

## Architecture

MCP Apps combine two MCP primitives: a **tool** that declares a UI resource in its metadata, and a **resource** that serves HTML rendered in a sandboxed iframe.

### Flow

1. **Tool registration**: Tool includes `_meta.ui.resourceUri` pointing to a `ui://` resource
2. **UI preloading**: Host can preload the resource before the tool is called (enables streaming inputs to the app)
3. **Resource fetch**: Host fetches the HTML from the server via `resources/read`
4. **Sandboxed rendering**: Hos

Related agents

Same protocol, similar job.

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW
Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.

MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70

CopilotKit

The Frontend for Agents & Generative UI. React + Angular

OPENCLAW

Machine-readable data

The same record, as JSON, for agents and crawlers.

{
  "facts": [
    {
      "factKey": "vendor",
      "category": "vendor",
      "label": "Vendor",
      "value": "Clawhub",
      "href": "https://clawhub.ai/tenequm/skills/mcp-best-practices",
      "sourceUrl": "https://clawhub.ai/tenequm/skills/mcp-best-practices",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-09T15:05:01.290Z",
      "isPublic": true
    },
    {
      "factKey": "protocols",
      "category": "compatibility",
      "label": "Protocol compatibility",
      "value": "OpenClaw",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-tenequm-mcp-best-practices/contract",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-tenequm-mcp-best-practices/contract",
      "sourceType": "contract",
      "confidence": "medium",
      "observedAt": "2026-10-09T15:05:01.290Z",
      "isPublic": true
    },
    {
      "factKey": "traction",
      "category": "adoption",
      "label": "Adoption signal",
      "value": "2.4K downloads",
      "href": "https://clawhub.ai/tenequm/mcp-best-practices",
      "sourceUrl": "https://clawhub.ai/tenequm/mcp-best-practices",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-09T15:05:01.290Z",
      "isPublic": true
    },
    {
      "factKey": "latest_release",
      "category": "release",
      "label": "Latest release",
      "value": "1.3.0",
      "href": "https://clawhub.ai/tenequm/mcp-best-practices",
      "sourceUrl": "https://clawhub.ai/tenequm/mcp-best-practices",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-10-06T12:18:33.750Z",
      "isPublic": true
    },
    {
      "factKey": "handshake_status",
      "category": "security",
      "label": "Handshake status",
      "value": "UNKNOWN",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-tenequm-mcp-best-practices/trust",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-tenequm-mcp-best-practices/trust",
      "sourceType": "trust",
      "confidence": "medium",
      "observedAt": null,
      "isPublic": true
    }
  ],
  "events": [
    {
      "eventType": "release",
      "title": "Release 1.3.0",
      "description": "Updated mcp-best-practices from 1.2.1 to 1.3.0. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - modified `references/error-handling.md` - modified `references/extensions-registry.md` - modified `references/mcp-apps.md` - modified `references/sdk-bugs.md` - modified `references/security-auth.md` - modified `references/spec-2026-07-28.md` - modified `references/tool-schema-guide.md` - modified `references/transport-patterns.md` - modified `references/v2-migration.md`",
      "href": "https://clawhub.ai/tenequm/mcp-best-practices",
      "sourceUrl": "https://clawhub.ai/tenequm/mcp-best-practices",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-10-06T12:18:33.750Z",
      "isPublic": true
    }
  ]
}

Record generated Oct 9, 2026.

Sponsored

Ads related to mcp-best-practices and adjacent AI workflows.