# README shows how to connect to the server

- **Pattern:** `ab-001832` (`mcp-server.tool-definitions.sdk-example`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001832
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001832)

## Why it matters

An MCP server without a connection example in its README forces every new user to read source code before they can use it. Unlike standard npm packages where the import pattern is obvious, MCP clients require a specific JSON config block with `command`, `args`, and `env` — there is no discoverable default. The MCP spec defines `mcpServers` configuration as the integration point; without it documented, adoption stalls and users connect incorrectly, leading to silent failures or version mismatches.

## Severity rationale

Info because missing connection docs create friction and integration errors but do not expose security vulnerabilities or corrupt data.

## Remediation

Add a Setup section to your README with the exact `mcpServers` JSON block for at least one client.

```markdown
## Setup

Add to `~/.claude/claude_desktop_config.json` (Claude Code) or `~/.cursor/mcp.json` (Cursor):

```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server@latest"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}
```
```

Include which env vars are required vs. optional, and list which MCP clients have been tested against this server.

## Detection

- **ID:** `sdk-example`
- **Severity:** `info`
- **What to look for:** Enumerate the SDK or framework used to build the MCP server. Count configuration patterns that follow official SDK examples. Check the README or documentation for a section explaining how to connect to this MCP server from a client. The minimum is a JSON config snippet showing the `mcpServers` configuration for at least one client (Claude Code, Cursor, etc.). Ideally includes: (1) the `command` and `args` to launch the server, (2) any required `env` variables, (3) which client configurations support this server.
- **Pass criteria:** README includes a connection example with the `mcpServers` JSON config block showing command, args, and any required env vars. Covers at least one client. The server must use an official MCP SDK (TypeScript, Python, etc.) with at least 3 standard patterns from the SDK examples.
- **Fail criteria:** No documentation on how to connect to the server from any MCP client.
- **Skip (N/A) when:** The server is internal (not intended for other users). All checks skip when no MCP server is detected.

- **Cross-reference:** For JSON-RPC compliance, see `jsonrpc-messages`.
- **Detail on fail:** `"README has no MCP client configuration example — users must read the source code to figure out how to connect this server to their AI coding assistant"`
- **Remediation:** Show users exactly how to connect:

  ```ts
  // src/index.ts — official MCP SDK usage
  import { Server } from "@modelcontextprotocol/sdk/server/index.js"
  const server = new Server({ name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } })
  ```

  ```markdown
  ## Setup

  Add this to your Claude Code config (`~/.claude/claude_desktop_config.json`):

  ```json
  {
    "mcpServers": {
      "my-server": {
        "command": "npx",
        "args": ["-y", "my-mcp-server"],
        "env": {
          "API_KEY": "your-api-key"
        }
      }
    }
  }
  ```
  ```

---

## External references

- external mcp-spec-client-config — https://modelcontextprotocol.io/docs/concepts/clients

Taxons: inference-contract, content-integrity

HTML version: https://auditbuffet.com/patterns/ab-001832