Skip to content

JPeetz/agent-skills / skills/api-backend/mcp-server-building

mcp-server-building

Verified

Use this skill when building, scaffolding or shipping an MCP server: deciding tools vs resources vs prompts, choosing Python (mcp 2.x) or TypeScript (@modelcontextprotocol/server 2.x), implementing primitives on the 2026-07-28 stateless spec (server/discover, _meta, resultType, InputRequiredResult/MRTR), wiring stdio or Streamable HTTP, adding OAuth, error handling and rate limits, testing with MCP Inspector, and deploying or publishing to the MCP Registry. Triggers on "build an MCP server", "expose my API to Claude/Cursor", "add a tool to my MCP server", "mcp server template", "my MCP server returns 421", "sampling is deprecated, now what".

FileKindSize
CHANGELOG.mdmarkdown3.5 KB
LICENSEother1.0 KB
SKILL.mdskill md24.2 KB
evals/evals.jsonconfig5.0 KB
references/mcp-spec-context.mdmarkdown14.5 KB
references/transport-guide.mdmarkdown10.9 KB
templates/server-py-template.pyscript11.8 KB
templates/server-ts-template.tsscript10.8 KB

evals/evals.json

View on GitHub
[
  {
    "id": "mcp-001",
    "description": "Contract-first planning before scaffolding",
    "input": "I want to build an MCP server for our internal ticketing system so Claude can search, create and close tickets.",
    "shouldTrigger": true,
    "expect": "Agent writes a contract table (name, primitive, trigger, input, output, side effects) before code, and classifies each capability as tool/resource/prompt.",
    "assertions": [
      "a contract table or equivalent per-capability spec precedes any implementation code",
      "search/create/close are tools (model-triggered, with side effects) and read-only data is a resource, not a tool",
      "writes are given an idempotency key and destructive close is given a confirmation flow"
    ]
  },
  {
    "id": "mcp-002",
    "description": "Stateless 2026-07-28 protocol usage, not the removed handshake",
    "input": "Scaffold an MCP server in Python with the current SDK.",
    "shouldTrigger": true,
    "expect": "Agent uses mcp 2.x MCPServer with decorators, relies on per-request _meta and server/discover, and does not write an initialize handler or session storage.",
    "assertions": [
      "imports MCPServer from mcp.server (not FastMCP from mcp.server.fastmcp)",
      "no initialize/initialized handler and no Mcp-Session-Id or session store is introduced",
      "server/discover, resultType and required _meta fields are accounted for (by the SDK or explicitly)"
    ]
  },
  {
    "id": "mcp-003",
    "description": "MRTR instead of server-initiated elicitation",
    "input": "My MCP tool needs to ask the user to confirm before deleting a record. How do I call back into the client?",
    "shouldTrigger": true,
    "expect": "Agent explains the back-channel is gone and the tool must return an InputRequiredResult (resultType input_required) with inputRequests and requestState, then read inputResponses on the client's retry.",
    "assertions": [
      "response is that servers no longer send elicitation/sampling/roots requests to the client",
      "the tool returns InputRequiredResult with inputRequests and requestState",
      "the retry carries inputResponses keyed by the same name the server chose"
    ]
  },
  {
    "id": "mcp-004",
    "description": "Transport choice and deployment: HTTP with auth, not stdio",
    "input": "Deploy our MCP server so multiple customers' agents can use it over the internet with per-customer access control.",
    "shouldTrigger": true,
    "expect": "Agent selects Streamable HTTP (not stdio, not SSE), wires OAuth 2.1 resource-server verification with AuthSettings/TokenVerifier, and configures the Host allowlist plus a shared requestState key for multiple workers.",
    "assertions": [
      "Streamable HTTP is chosen and stdio is rejected for multi-tenant remote use",
      "token verifier + AuthSettings (issuer, resource_server_url, required_scopes) are configured",
      "allowed_hosts / transport_security is set and the 421 failure mode is mentioned",
      "multi-worker requestState sealing is addressed"
    ]
  },
  {
    "id": "mcp-005",
    "description": "Error semantics: ToolError vs MCPError",
    "input": "My MCP tool returns the string 'Error: record not found' when the lookup fails. Is that OK?",
    "shouldTrigger": true,
    "expect": "Agent says no — a returned string is isError:false and the model treats it as the answer — and switches to raising ToolError (model-recoverable) or MCPError (request-level), with ResourceNotFoundError for missing resources.",
    "assertions": [
      "explains that isError stays false for a returned string, so the model believes it succeeded",
      "recommends ToolError / isError:true for recoverable execution failures",
      "reserves MCPError for request-level rejection and does not use it for lookup misses"
    ]
  },
  {
    "id": "mcp-006",
    "description": "Caching hints on list results",
    "input": "Tools/list is re-fetched constantly by our gateway and the tool catalog never changes. Can we cache it?",
    "shouldTrigger": true,
    "expect": "Agent sets ttlMs and cacheScope (required on cacheable results), keeping cacheScope private if the list varies per caller, and notes deterministic tool order.",
    "assertions": [
      "ttlMs and cacheScope are set rather than left at the 0/private default",
      "cacheScope public is only used when the payload is identical for every caller",
      "deterministic tool ordering is mentioned as what makes client caching work"
    ]
  },
  {
    "id": "mcp-007",
    "description": "Near-miss: consuming MCP servers in a client, not building one",
    "input": "How do I configure Claude Desktop to use an existing MCP server from npm?",
    "shouldTrigger": false,
    "expect": "Host/client configuration of a third-party server is consumption, not server building; the skill should not activate and no server code should be produced.",
    "assertions": [
      "skill does not activate for client-side or host-configuration questions",
      "no server scaffolding, primitives or deployment work is started"
    ]
  }
]
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall