MCP server authoring standards

An MCP (Model Context Protocol) server connects Claude to your tools, data, or systems. The server exposes resources Claude can read and tools Claude can invoke inside conversations. Configs ship standalone at mcp/<name>.json or plugin-bundled at plugins/<plugin>/.mcp.json.

This page is two layers: Anthropic’s official guidance, then the RBA tailoring on top.

Anthropic’s best practices

Source: Claude Code — MCP and the Model Context Protocol spec.

Transports

MCP servers connect over one of three transports:

• stdio — a local process Claude Code launches (command + args). Best for local tools and the default for bundled servers.
• SSE — a remote server over server-sent events (url).
• HTTP — a remote streamable-HTTP server (url).

Scopes

Anthropic defines three configuration scopes; pick deliberately:

• local — just you, just this project (not committed).
• project — committed .mcp.json, shared with everyone on the repo.
• user — you, across all your projects.

The catalog ships project-scope-shaped configs (a committed .mcp.json / mcp/<name>.json).

.mcp.json shape

{
  "mcpServers": {
    "<server-name>": {
      "command": "<executable>",
      "args": ["..."],
      "env": { "VAR": "value" }
    }
  }
}

A remote server uses "type": "sse" | "http" and "url" instead of command/args.

Resources vs. tools vs. prompts

MCP servers can expose three primitives. Anthropic’s guidance:

• Resources — addressable, read-only data Claude can pull in (@server:protocol://resource). Idempotent reads.
• Tools — model-invoked actions, possibly with side effects.
• Prompts — reusable prompt templates surfaced as slash commands.

Security

Anthropic explicitly warns: use third-party MCP servers at your own risk and confirm you trust them. Servers that fetch external content can carry prompt-injection risk. Use OAuth where the server supports it, and supply credentials via environment variables rather than embedding them.

How RBA tailors this

Pick the right primitive (RBA decision rule)

Use a resource when…	Use a tool when…
Claude needs to read state	Claude needs to do something
The data is addressable by ID/URL	The action takes parameters
Re-fetching is cheap and idempotent	The action has side effects
e.g. a project record, a schema, a doc	e.g. trigger a deploy, run a query

A well-designed server exposes both — resources first (what does this system contain?), tools second (what can Claude do to it?).

Standalone shape (RBA wrapper)

The bundled .mcp.json is exactly Anthropic’s shape. The standalone shape wraps one server in catalog metadata:

{
  "name": "<server-name>",
  "description": "<one sentence>",
  "primitive": false,
  "platforms": [], "disciplines": [], "lifecycle": [], "tags": [], "outcomes": [],
  "server": { "command": "<executable>", "args": ["..."], "env": { "VAR": "value" } }
}

Required: name, description, server. Optional: primitive: true for cross-cutting foundation servers, plus any facets (platforms, disciplines, lifecycle, tags, outcomes) that describe it. Plugin-bundled servers add an RBA-convention description field per server (the catalog page reads it) and inherit primitive from rba-meta.json. See plugin standards for the facet model.

Naming (RBA)

• Server name: kebab-case, <system>-<purpose> — sitecore-graphql, linear-tickets.
• Resource URIs: stable, hierarchical — <scheme>://<system>/<type>/<id>.
• Tool names: verb_object snake_case — create_issue, trigger_deploy.

Security baseline (RBA tightens Anthropic’s warning into rules)

1. Default-deny: the server starts read-only against a single scoped namespace.
2. Explicit scope grants: the user opts into specific projects/repos in their config.
3. No production writes by default: any mutating tool against production requires an explicit confirmation env var.
4. Secrets via env vars or keychain only — never embedded in the committed config (Anthropic’s guidance, made a hard rule).
5. Audit trail: log every tool invocation (timestamp, tool, args) to a local file the user can inspect.

Documentation requirement (RBA)

The README / catalog page must cover: what the server does, resources exposed (URI patterns), tools exposed (params + side effects), required configuration, security notes (what it needs, what it can’t do), and failure modes (auth/network/rate-limit).

Quality checklist

1. Transport and scope are chosen deliberately (Anthropic).
2. Resources outnumber tools — read access broad, write access narrow (Anthropic + RBA).
3. Config has name, description, server; optional primitive: true and facets describe it (standalone) (RBA).
4. Server name is <system>-<purpose> kebab-case (RBA).
5. Every tool documents its side effects.
6. Default config is read-only against one scoped namespace (RBA security baseline).
7. No credentials in the committed config (Anthropic + RBA).
8. The server passes a smoke test against a non-production endpoint.

Anti-patterns

• Tools that take a free-form query parameter with no schema constraints
• Default config that grants production write access
• Credentials embedded in .mcp.json or mcp/<name>.json (Anthropic security warning)
• Server name matching the company name with no purpose suffix
• One mega-tool that does many things — split into focused tools
• Trusting external-content responses without treating them as untrusted input