From REST to MCP (2/2): The Design Shift

Intro

In part one, we saw why the environments of MCPs and REST APIs are fundamentally different, and therefore concluded that their design should also differ. In this article we will go through some MCP design good practices, but we will have a REST intro to each one. My goal is to elaborate the shift in design between the two.

The examples below come from Sentry, Notion, GitHub and Stripe. We will see how the developers in those companies realized that fact that REST and MCP should have different design by comparing the way a specific operation is implemented in same company's REST API and MCP Server.

1. Design around intent

REST APIs expose operations that are ideally built around resources. They impose some level of granularity that might shift some of the orchestration/aggregation work to the client code. That work is developed and tested before the application is deployed.