mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-03-20 11:33:08 +00:00
add(plugin): mcp-server-dev — skills for building MCP servers
Three skills guiding developers through MCP server design: - build-mcp-server: entry-point decision guide (remote HTTP vs MCPB vs local) - build-mcp-app: interactive UI widgets rendered in chat - build-mcpb: bundled local servers with runtime Includes reference files for scaffolds, tool design, auth (DCR/CIMD), widget templates, manifest schema, and local security hardening.
This commit is contained in:
Tobin South
@@ -0,0 +1,73 @@
|
||||
# Auth for MCP Servers
|
||||
|
||||
Auth is the reason most people end up needing a **remote** server even when a local one would be simpler. OAuth redirects, token storage, and refresh all work cleanly when there's a real hosted endpoint to redirect back to.
|
||||
|
||||
---
|
||||
|
||||
## The three tiers
|
||||
|
||||
### Tier 1: No auth / static API key
|
||||
|
||||
Server reads a key from env. User provides it once at setup. Done.
|
||||
|
||||
```typescript
|
||||
const apiKey = process.env.UPSTREAM_API_KEY;
|
||||
if (!apiKey) throw new Error("UPSTREAM_API_KEY not set");
|
||||
```
|
||||
|
||||
Works for local stdio, MCPB, and remote servers alike. If this is all you need, stop here.
|
||||
|
||||
### Tier 2: OAuth 2.0 via Dynamic Client Registration (DCR)
|
||||
|
||||
The MCP host (Claude desktop, Claude Code, etc.) discovers your server's OAuth metadata, **registers itself as a client dynamically**, runs the auth-code flow, and stores the token. Your server never sees credentials — it just receives bearer tokens on each request.
|
||||
|
||||
This is the **recommended path** for any remote server wrapping an OAuth-protected API.
|
||||
|
||||
**Server responsibilities:**
|
||||
|
||||
1. Serve OAuth Authorization Server Metadata (RFC 8414) at `/.well-known/oauth-authorization-server`
|
||||
2. Serve an MCP-protected-resource metadata document pointing at (1)
|
||||
3. Implement (or proxy to) a DCR endpoint that hands out client IDs
|
||||
4. Validate bearer tokens on incoming `/mcp` requests
|
||||
|
||||
Most of this is boilerplate — the SDK has helpers. The real decision is whether you **proxy** to the upstream's OAuth (if they support DCR) or run your own **shim** authorization server that exchanges your tokens for upstream tokens.
|
||||
|
||||
```
|
||||
┌─────────┐ DCR + auth code ┌──────────────┐ upstream OAuth ┌──────────┐
|
||||
│ MCP host│ ──────────────────> │ Your MCP srv │ ─────────────────> │ Upstream │
|
||||
└─────────┘ <── bearer token ── └──────────────┘ <── access token ──└──────────┘
|
||||
```
|
||||
|
||||
### Tier 3: CIMD (Client ID Metadata Document)
|
||||
|
||||
An alternative to DCR for ecosystems that don't want dynamic registration. The host publishes its client metadata at a well-known URL; your server fetches it, validates it, and issues a client credential. Lower friction than DCR for the host, slightly more work for you.
|
||||
|
||||
Use CIMD when targeting hosts that advertise CIMD support in their client metadata. Otherwise default to DCR — it's more broadly implemented.
|
||||
|
||||
---
|
||||
|
||||
## Hosting providers with built-in DCR/CIMD support
|
||||
|
||||
Several MCP-focused hosting providers handle the OAuth plumbing for you — you implement tool logic, they run the authorization server. Check their docs for current capabilities. If the user doesn't have strong hosting preferences, this is usually the fastest path to a working OAuth-protected server.
|
||||
|
||||
---
|
||||
|
||||
## Local servers and OAuth
|
||||
|
||||
Local stdio servers **can** do OAuth (open a browser, catch the redirect on a localhost port, stash the token in the OS keychain). It's fragile:
|
||||
|
||||
- Breaks in headless/remote environments
|
||||
- Every user re-does the dance
|
||||
- No central token refresh or revocation
|
||||
|
||||
If OAuth is required, lean hard toward remote HTTP. If you *must* ship local + OAuth, the `@modelcontextprotocol/sdk` includes a localhost-redirect helper, and MCPB is the right packaging so at least the runtime is predictable.
|
||||
|
||||
---
|
||||
|
||||
## Token storage
|
||||
|
||||
| Deployment | Store tokens in |
|
||||
|---|---|
|
||||
| Remote, stateless | Nowhere — host sends bearer each request |
|
||||
| Remote, stateful | Session store keyed by MCP session ID (Redis, etc.) |
|
||||
| MCPB / local | OS keychain (`keytar` on Node, `keyring` on Python). **Never plaintext on disk.** |
|
||||
@@ -0,0 +1,151 @@
|
||||
# Remote Streamable-HTTP MCP Server — Scaffold
|
||||
|
||||
Minimal working servers in both recommended frameworks. Start here, then add tools.
|
||||
|
||||
---
|
||||
|
||||
## TypeScript SDK (`@modelcontextprotocol/sdk`)
|
||||
|
||||
```bash
|
||||
npm init -y
|
||||
npm install @modelcontextprotocol/sdk zod express
|
||||
npm install -D typescript @types/express @types/node tsx
|
||||
```
|
||||
|
||||
**`src/server.ts`**
|
||||
|
||||
```typescript
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
||||
import express from "express";
|
||||
import { z } from "zod";
|
||||
|
||||
const server = new McpServer({
|
||||
name: "my-service",
|
||||
version: "0.1.0",
|
||||
});
|
||||
|
||||
// Pattern A: one tool per action
|
||||
server.tool(
|
||||
"search_items",
|
||||
"Search items by keyword. Returns up to `limit` matches ranked by relevance.",
|
||||
{
|
||||
query: z.string().describe("Search keywords"),
|
||||
limit: z.number().int().min(1).max(50).default(10),
|
||||
},
|
||||
async ({ query, limit }) => {
|
||||
const results = await upstreamApi.search(query, limit);
|
||||
return {
|
||||
content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
server.tool(
|
||||
"get_item",
|
||||
"Fetch a single item by its ID.",
|
||||
{ id: z.string() },
|
||||
async ({ id }) => {
|
||||
const item = await upstreamApi.get(id);
|
||||
return { content: [{ type: "text", text: JSON.stringify(item) }] };
|
||||
},
|
||||
);
|
||||
|
||||
// Streamable HTTP transport (stateless mode — simplest)
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
|
||||
app.post("/mcp", async (req, res) => {
|
||||
const transport = new StreamableHTTPServerTransport({
|
||||
sessionIdGenerator: undefined, // stateless
|
||||
});
|
||||
res.on("close", () => transport.close());
|
||||
await server.connect(transport);
|
||||
await transport.handleRequest(req, res, req.body);
|
||||
});
|
||||
|
||||
app.listen(process.env.PORT ?? 3000);
|
||||
```
|
||||
|
||||
**Stateless vs stateful:** The snippet above creates a fresh transport per request (stateless). Fine for most API-wrapping servers. If tools need to share state across calls in a session (rare), use a session-keyed transport map — see the SDK's `examples/server/simpleStreamableHttp.ts`.
|
||||
|
||||
---
|
||||
|
||||
## FastMCP 2.0 (Python)
|
||||
|
||||
```bash
|
||||
pip install fastmcp
|
||||
```
|
||||
|
||||
**`server.py`**
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP(name="my-service")
|
||||
|
||||
@mcp.tool
|
||||
def search_items(query: str, limit: int = 10) -> list[dict]:
|
||||
"""Search items by keyword. Returns up to `limit` matches ranked by relevance."""
|
||||
return upstream_api.search(query, limit)
|
||||
|
||||
@mcp.tool
|
||||
def get_item(id: str) -> dict:
|
||||
"""Fetch a single item by its ID."""
|
||||
return upstream_api.get(id)
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp.run(transport="http", host="0.0.0.0", port=3000)
|
||||
```
|
||||
|
||||
FastMCP derives the JSON schema from type hints and the docstring becomes the tool description. Keep docstrings terse and action-oriented — they land in Claude's context window verbatim.
|
||||
|
||||
---
|
||||
|
||||
## Search + execute pattern (large API surface)
|
||||
|
||||
When wrapping 50+ endpoints, don't register them all. Two tools:
|
||||
|
||||
```typescript
|
||||
const CATALOG = loadActionCatalog(); // { id, description, paramSchema }[]
|
||||
|
||||
server.tool(
|
||||
"search_actions",
|
||||
"Find available actions matching an intent. Call this first to discover what's possible. Returns action IDs, descriptions, and parameter schemas.",
|
||||
{ intent: z.string().describe("What you want to do, in plain English") },
|
||||
async ({ intent }) => {
|
||||
const matches = rankActions(CATALOG, intent).slice(0, 10);
|
||||
return { content: [{ type: "text", text: JSON.stringify(matches, null, 2) }] };
|
||||
},
|
||||
);
|
||||
|
||||
server.tool(
|
||||
"execute_action",
|
||||
"Execute an action by ID. Get the ID and params schema from search_actions first.",
|
||||
{
|
||||
action_id: z.string(),
|
||||
params: z.record(z.unknown()),
|
||||
},
|
||||
async ({ action_id, params }) => {
|
||||
const action = CATALOG.find(a => a.id === action_id);
|
||||
if (!action) throw new Error(`Unknown action: ${action_id}`);
|
||||
validate(params, action.paramSchema);
|
||||
const result = await dispatch(action, params);
|
||||
return { content: [{ type: "text", text: JSON.stringify(result) }] };
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
`rankActions` can be simple keyword matching to start. Upgrade to embeddings if precision matters.
|
||||
|
||||
---
|
||||
|
||||
## Deployment checklist
|
||||
|
||||
- [ ] `POST /mcp` responds to `initialize` with server capabilities
|
||||
- [ ] `tools/list` returns your tools with complete schemas
|
||||
- [ ] Errors return structured MCP errors, not HTTP 500s with HTML bodies
|
||||
- [ ] CORS headers set if browser clients will connect
|
||||
- [ ] Health check endpoint separate from `/mcp` (hosts poll it)
|
||||
- [ ] Secrets from env vars, never hardcoded
|
||||
- [ ] If OAuth: DCR endpoint implemented — see `auth.md`
|
||||
@@ -0,0 +1,112 @@
|
||||
# Tool Design — Writing Tools Claude Uses Correctly
|
||||
|
||||
Tool schemas and descriptions are prompt engineering. They land directly in Claude's context and determine whether Claude picks the right tool with the right arguments. Most MCP integration bugs trace back to vague descriptions or loose schemas.
|
||||
|
||||
---
|
||||
|
||||
## Descriptions
|
||||
|
||||
**The description is the contract.** It's the only thing Claude reads before deciding whether to call the tool. Write it like a one-line manpage entry plus disambiguating hints.
|
||||
|
||||
### Good
|
||||
|
||||
```
|
||||
search_issues — Search issues by keyword across title and body. Returns up
|
||||
to `limit` results ranked by recency. Does NOT search comments or PRs —
|
||||
use search_comments / search_prs for those.
|
||||
```
|
||||
|
||||
- Says what it does
|
||||
- Says what it returns
|
||||
- Says what it *doesn't* do (prevents wrong-tool calls)
|
||||
|
||||
### Bad
|
||||
|
||||
```
|
||||
search_issues — Searches for issues.
|
||||
```
|
||||
|
||||
Claude will call this for anything vaguely search-shaped, including things it can't do.
|
||||
|
||||
### Disambiguate siblings
|
||||
|
||||
When two tools are similar, each description should say when to use the *other* one:
|
||||
|
||||
```
|
||||
get_user — Fetch a user by ID. If you only have an email, use find_user_by_email.
|
||||
find_user_by_email — Look up a user by email address. Returns null if not found.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parameter schemas
|
||||
|
||||
**Tight schemas prevent bad calls.** Every constraint you express in the schema is one fewer thing that can go wrong at runtime.
|
||||
|
||||
| Instead of | Use |
|
||||
|---|---|
|
||||
| `z.string()` for an ID | `z.string().regex(/^usr_[a-z0-9]{12}$/)` |
|
||||
| `z.number()` for a limit | `z.number().int().min(1).max(100).default(20)` |
|
||||
| `z.string()` for a choice | `z.enum(["open", "closed", "all"])` |
|
||||
| optional with no hint | `.optional().describe("Defaults to the caller's workspace")` |
|
||||
|
||||
**Describe every parameter.** The `.describe()` text shows up in the schema Claude sees. Omitting it is leaving money on the table.
|
||||
|
||||
```typescript
|
||||
{
|
||||
query: z.string().describe("Keywords to search for. Supports quoted phrases."),
|
||||
status: z.enum(["open", "closed", "all"]).default("open")
|
||||
.describe("Filter by status. Use 'all' to include closed items."),
|
||||
limit: z.number().int().min(1).max(50).default(10)
|
||||
.describe("Max results. Hard cap at 50."),
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Return shapes
|
||||
|
||||
Claude reads whatever you put in `content[].text`. Make it parseable.
|
||||
|
||||
**Do:**
|
||||
- Return JSON for structured data (`JSON.stringify(result, null, 2)`)
|
||||
- Return short confirmations for mutations (`"Created issue #123"`)
|
||||
- Include IDs Claude will need for follow-up calls
|
||||
- Truncate huge payloads and say so (`"Showing 10 of 847 results. Refine the query to narrow down."`)
|
||||
|
||||
**Don't:**
|
||||
- Return raw HTML
|
||||
- Return megabytes of unfiltered API response
|
||||
- Return bare success with no identifier (`"ok"` after a create — Claude can't reference what it made)
|
||||
|
||||
---
|
||||
|
||||
## How many tools?
|
||||
|
||||
| Tool count | Guidance |
|
||||
|---|---|
|
||||
| 1–15 | One tool per action. Sweet spot. |
|
||||
| 15–30 | Still workable. Audit for near-duplicates that could merge. |
|
||||
| 30+ | Switch to search + execute. Optionally promote the top 3–5 to dedicated tools. |
|
||||
|
||||
The ceiling isn't a hard protocol limit — it's context-window economics. Every tool schema is tokens Claude spends *every turn*. Thirty tools with rich schemas can eat 3–5k tokens before the conversation even starts.
|
||||
|
||||
---
|
||||
|
||||
## Errors
|
||||
|
||||
Return MCP tool errors, not exceptions that crash the transport. Include enough detail for Claude to recover or retry differently.
|
||||
|
||||
```typescript
|
||||
if (!item) {
|
||||
return {
|
||||
isError: true,
|
||||
content: [{
|
||||
type: "text",
|
||||
text: `Item ${id} not found. Use search_items to find valid IDs.`,
|
||||
}],
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
The hint ("use search_items…") turns a dead end into a next step.
|
||||
Reference in New Issue
Block a user