David Soria Parra, co-creator of the Model Context Protocol at Anthropic, recently shared hard-won design lessons from MCP's first year in production. The core message hits like a wall: teams are building MCP servers completely wrong—and it's tanking agent performance. His six lessons aren't theoretical debates; they're corrective patterns emerging from watching developers repeatedly make the same mistakes as they rush to wrap existing REST APIs with MCP tooling.

Stop Wrapping CRUD Endpoints as MCP

Here's the trap every team falls into. You have a legacy REST API with endpoints like GET /users, POST /orders, PATCH /documents/:id—and you wrap each one as an individual MCP tool. Sound efficient? It's not. For a frontend developer calling your API directly, that granularity makes sense. For an autonomous agent trying to accomplish work, it's a disaster. Agents end up sequencing dozens of REST calls, burning through context window on what should be single operations: 'Prepare this customer for onboarding,' or 'Find and review this contract.' Each of those, in CRUD terms, is 30-40 API calls the agent has to plan, execute, and check—wasteful and high-failure. The fix is a mindset shift. You're no longer designing interfaces for developers making CRUD calls. You're designing interfaces for agents performing business operations. Instead of exposing get_user, create_order, patch_document, list_permissions as separate tools, wrap them into one tool: prepare_user_for_onboarding(user_id) returns OnboardingResult. One call, structured result, agent moves on. The backend stays the same—the agent experience is not comparable.

Progressive Discovery

MCP servers with 30+ tools dump every description into context at session start. With multiple servers connected, that climbs to a hundred tool descriptions before the agent even starts working. The costs compound: worse tool selection as options become confusable, higher input-token costs per request, increased latency, and actual data getting squeezed out by tool metadata that's never invoked. Progressive discovery fixes this—agents fetch tools as needed from a small categorized index rather than consuming the full catalog upfront. Audit your server's tool count now. If you're exposing 20+ flat tools, split into focused servers or implement category-based on-demand loading.

Skills vs MCP: Not Competitors

Anthropic also ships a Skills system, and teams keep asking which wins. Neither—they answer different questions. Skills handle local, procedural, CLI-utility-driven work: ffmpeg video processing, git operations, build scripts. Low cost to build and run, no auth overhead needed. MCP handles actions requiring authorization, RBAC, audit logs, observability, stable contracts with external systems—customer data, financials, enterprise integrations. Decision rule from Soria Parra: use the simplest mechanism that solves the problem. If a Skill works, ship the Skill. MCP servers aren't free to build, run, or maintain.

Enterprise Considerations

Production deployments need an MCP gateway handling auth, rate limiting, audit logging, and routing between internal MCP servers. This isn't optional for enterprise—it's infrastructure. Without centralized gateway management, you're flying blind on which agents accessed what customer data, how many calls hit your backend per minute, and whether that behavior is normal or compromised.

Tool Discovery and Versioning

Tool signatures are contracts. Breaking changes break existing agents mid-workflow. Beyond versioning, tools need to be discoverable by design—categorization, naming conventions, and descriptions matter exponentially more for agentic systems than traditional APIs where developers read docs manually. An agent scanning your tool list needs clear intent signals from names like find_and_review_contract(party, period) returning ContractReview—not ambiguous wrappers that force the model to guess at purpose.

What This Means For Claude Code Users

If you're building MCP servers for your Claude Code workflow: audit whether tools are action-shaped or CRUD-shaped and refactor anything requiring multiple calls for one business task. If a server exposes 15+ tools, implement progressive discovery or split it up. For deterministic local procedures like file processing or git operations, use Skills instead of building unnecessary MCP infrastructure.

Key Takeaways

  • Don't wrap REST/CRUD endpoints as individual MCP tools—compose them into action-shaped operations
  • Implement progressive tool discovery to avoid dumping 20+ tools into context at session start
  • Use Skills for local procedural work; reserve MCP for auth-required, audit-logged operations
  • Enterprise deployments need a centralized gateway for auth, rate limiting, and observability
  • Tool naming and descriptions are discoverability signals—design them like search metadata
  • Version your tool contracts with semantic versioning to avoid breaking production agents

The Bottom Line

The CRUD-wrapping pattern is the MCP ecosystem's collective footgun—and it's being distributed at scale right now. If you're shipping MCP servers that expose individual REST endpoints as tools, you're not building for agents—you're building an ORM with extra steps and worse performance. Fix your granularity first.