DEV Community: Ibrahim Mohammed

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

Ibrahim Mohammed — Mon, 13 Jul 2026 16:41:54 +0000

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.

With MCP, the agent often builds that workflow at runtime. Which means the agent is now responsible for figuring out how to combine different tools to fulfill the user intent. That added responsibility simply means higher error probability and more context usage. To reduce that, we should design around user intents not resources.

A tool should represent one coherent user intent and push more of the deterministic orchestration into the server. This does not mean creating a manage_everything tool. The useful boundary is an outcome that the agent can sensibly choose.

Example

Setting up a Sentry project requires separate REST operations across project, repository, and client-key resources:

# Create the project
POST /api/0/teams/{organization_slug}/{team_slug}/projects/

# Link its repository
POST /api/0/projects/{organization_slug}/{project_slug}/repo/

# Retrieve an active client key and its DSN
GET /api/0/projects/{organization_slug}/{project_slug}/keys/

# Create a key only if no usable one exists
POST /api/0/projects/{organization_slug}/{project_slug}/keys/

Sentry documents these operations separately under Create a New Project, Link a Repository to a Project, and the endpoints to list or create client keys. Its MCP server exposes the complete setup through one create_project tool:

create_project(
  organizationSlug="acme",
  teamSlug="backend",
  name="payments-api",
  platform="python",
  repository="acme/payments"
)

The tool creates the project, connects the repository, retrieves an active DSN, and creates a fallback client key when needed. The agent chooses the setup outcome without carrying the project slug through the sequence or adding every intermediate response to the conversation.

2. Batch repeated operations

REST's uniform interface does not define a standard bulk-operation primitive, so APIs commonly scope changes to one item. That worked well enough when a person used a UI: create one page, fill it, then create the next. Human-paced interaction rarely needed many complete items at once.

An agent creates a different workload. A user can ask for a research workspace, project plan, or book and expect several pages from one request. Without batching, the agent repeats the same tool call and rebuilds its arguments before checking each result. Every call consumes more context and gives the agent another chance to skip an item or let the inputs drift.

A batch tool accepts the collection once and moves the loop into deterministic server code, or even a more efficient native bulk operation that our datastore supports.

Example

Notion's Create a page REST endpoint creates one page per request. Creating three pages under the same parent requires three calls:

POST /v1/pages  # "API migration"
POST /v1/pages  # "Launch checklist"
POST /v1/pages  # "Incident review"

Notion's notion-create-pages MCP tool accepts the collection directly:

notion-create-pages(
  parent={ page_id: "engineering_page_id" },
  pages=[
    { properties: { title: "API migration" }, content: "..." },
    { properties: { title: "Launch checklist" }, content: "..." },
    { properties: { title: "Incident review" }, content: "..." }
  ]
)

Adding another page changes the collection, not the number of tool calls.

Batching still needs a clear boundary. The tool should document its input limits, whether it processes items atomically or independently, and how it reports a partial failure.

3. Consolidate closely related operations

REST can place related operations under different methods and routes. MCP puts every tool in one flat selection surface. Create and update are different actions, but separate tools can repeat the same context and compete for selection when they share most of their language and inputs.

Consider an issue tracking conversation with an AI agent , a user may say "make sure this bug is tracked with the notes we discussed so far" without specifying whether to create an issue or update one. A single combined tool should handle both scenarios, whether the agent is delegating the decision into the tool implementation (ex: upsertIssue(key, value)) or the agent is making the choice via an additional parameter (ex: writeIssue(id?, value, operation = 'create' | 'update)). Any of those would be better than registering 2 tools.

This saves context and can also improve selection accuracy. The ToolScope study supports this narrower selection claim, not a rule to merge every related operation.

Example

GitHub's REST API exposes issue creation and update as 2 separate endpoints:

POST  /repos/{owner}/{repo}/issues
PATCH /repos/{owner}/{repo}/issues/{issue_number}

GitHub's issue_write MCP tool groups them behind one explicit parameter:

issue_write(
  issue_number: number, # gets ignored if passed method is create
  method="create" | "update",
  owner: string,
  repo: string,
  title: string,
  # ... other 9 fields
)

The method parameter keeps create and update distinct. If we were to keep create and update as 2 separate tools, that means we would be copying all the documentation for all 13 parameters across both tools, which would eventually bloat the context.

4. Make semantics explicit

With REST, the URL identifies a resource and the HTTP method describes the operation. Status codes classify the result, while headers add protocol-level context. Application code interprets those signals through branches written by a developer.

With MCP, an agent usually sees only a tool call and its result. It doesn't have a client-side logic that translates an HTTP status to a specific user facing message. A bare Unauthorized leaves several questions open: what failed, whether state changed, and what the user should do next.

The tool should turn that implicit contract into explicit inputs and results. Detailed semantics give the model fewer interpretations and a safer recovery path.

Example

A REST API may rely on the method, route, and status code:

PATCH /orders/ORD-42
Content-Type: application/json

{
  "shipping_address": "12 Market Street, Cairo"
}

401 Unauthorized

The programmed client's 401 branch may already know how authentication works and which sign-in screen to open. The equivalent update_order(order_id="ORD-42", shipping_address="12 Market Street, Cairo") tool should return that knowledge:

{
  "error": "AUTHENTICATION_REQUIRED",
  "message": "The shipping address for ORD-42 was not updated because the store account session has expired.",
  "state_changed": false,
  "recovery": "Ask the user to reconnect the store account through the account connection UI, then retry update_order with the same arguments. Do not ask for credentials in chat."
}

The MCP specification supports structured results, so explicit feedback does not require giving up machine-readable errors.

5. Treat documentation as control flow

With REST, developers usually read documentation while building an integration. Once the client ships, its integration logic keeps working even if the reference becomes incomplete, outdated, or buried in a Slack thread.

With MCP, the agent reads the tool name, description, and parameter descriptions at runtime. Documentation does not just support the integration. It prompts the agent and becomes an essential part of the control flow.

The wording affects which tool the model selects and which arguments it builds. Changing a REST description does not change a client that has already compiled its integration logic. Changing an MCP description can change behavior while the schema and handler stay untouched. A commit named docs: clarify wording can now change production behavior.

Documentation changes can therefore cause regressions and should be tested against representative user requests.

Example

Before invocation, the model may know a log-search capability only through this definition:

search_logs(service, query, start_time, end_time)
"Search logs."

The description leaves important decisions to the model. It does not say which logs the tool searches, what identifies a service, how it interprets time ranges, or whether it includes audit events.

A useful definition carries the knowledge that would otherwise live in an API guide:

search_logs(service, query, start_time, end_time)
"Search application logs when investigating runtime behavior. `service` must
match a deployed service name. Times are UTC and the range cannot exceed 24
hours. This tool does not search security audit events."

The expanded description tells the model when to select the tool and how to construct a valid call.

6. Suggest relevant next actions

HATEOAS (Hypermedia as the Engine of Application State) is part of REST's original uniform-interface constraint. It simply means the server should return links that describe valid next transitions. Most REST APIs ignore this part because they'd view as impractical (even though the REST author is skeptical about APIs being called RESTful without HATEOS). Anyways, this concept should now be revived, it will be more relevant in an MCP than in a REST(or REST-ish) API.

Again, an agent chooses the next step at runtime. If the result names a relevant tool, explains why it applies, and carries known arguments forward, the agent does not have to search the tool surface or infer the transition from raw state.

Example

Sentry's get_trace_details MCP tool does this in its response. When a trace contains an AI conversation, the result includes the trace summary and a structured suggestedActions entry. The tool's response test covers this behavior:

{
  "structuredContent": {
    "suggestedActions": [
      {
        "type": "tool_call",
        "toolName": "execute_sentry_tool",
        "arguments": {
          "name": "get_ai_conversation_details",
          "arguments": {
            "organizationSlug": "sentry-mcp-evals",
            "conversationId": "conv-trace-snapshot"
          }
        },
        "reason": "Fetch the full transcript for this AI conversation."
      }
    ]
  }
}

The response selects the next tool, explains why it applies, and carries forward the organization and conversation identifiers found in the trace. The agent can move from the trace overview to the full conversation without reconstructing that workflow from documentation.

7. Support field filtering

REST APIs commonly return a fixed resource representation, then let application code extract the fields it needs from it. Client-defined projections is considered one of the best practices by Microsoft, although many REST APIs do not provide them. That's why we hear that one of GraphQL's advantages is that it promotes against over-fetching.

With MCP, the tool should return the smallest complete result needed for the current decision. The model has to interpret every returned field, and common clients may keep the result in conversation history. Irrelevant data consumes context now and may keep consuming it on later turns.

A smaller result also gives the model less state to distinguish before choosing its next action.

Example

A REST field projection may look like this:

GET /customers/C-17?fields=id,name,riskStatus

The MCP tool can expose the same filtering idea directly:

inspect_customer(
  customer_id="C-17",
  fields=["customer_id", "display_name", "risk_status", "risk_reasons"]
)
→ {
    "customer_id": "C-17",
    "display_name": "Contoso Ltd.",
    "risk_status": "review",
    "risk_reasons": ["billing address changed after payment"]
  }

Both interfaces use the same projection pattern, and that is fine. With MCP, filtering matters more because every returned field may enter the model's context. The fields parameter lets the agent request only the properties needed for its current decision.

8. Guard destructive operations

With REST, an endpoint usually assumes that client code has already selected the intended operation and resource, this is enhanced by a good UI/UX that warns users of destructive operations, and the overall deterministic behavior of the app doesn't make this a big issue.

With MCP, a model makes that choice at runtime. Schema and permission checks can show that a mutation is well-formed and allowed, but they cannot show that the agent understood what the user wanted.

A tool can guard destructive operations before and after execution. Before the call, its description can instruct the agent to warn the user and ask for explicit confirmation. For higher-risk operations, the client can enforce that confirmation. After the call, the result should confirm what changed and provide a recovery path through soft deletion or a restorable backup.

Example

remove_file(path)
"Remove a file. Before calling, warn the user that the file will be deleted and ask for explicit confirmation."

remove_file(path="/repo/config.yml")
→ {
    "removed": "/repo/config.yml",
    "state_changed": true,
    "backup_path": ".backups/7fd2/config.yml",
    "backup_expires_at": "2026-07-20T12:00:00Z"
  }

This level of protection makes sense for deletion. Not every update needs the same ceremony.

9. Disclose tools progressively

A REST API may expose hundreds of endpoints because each application selects the subset it needs during development. That selection happens once, before the application runs.

An agent cannot make the same permanent selection because the useful subset depends on the current request. MCP clients should progressively disclose specialist tools as the user's intent becomes clearer.

Tool definitions also consume context. Loading every definition at the start spends context on capabilities that may never be used and gives the model more similar options to confuse. Progressive disclosure adds a discovery step, but it narrows both the initial prompt and the selection problem when the full surface is large enough to justify it.

Example

Search-first meta-tools are common when an MCP server wraps a large API. Stripe exposes a few broad tools instead of one tool per API method:

stripe_api_search            → find the API method
stripe_api_details           → load its parameters
stripe_api_read / stripe_api_write → execute it

Only the selected method's details enter context. The extra discovery step makes sense for a large surface. Five clear tools do not need a meta-tool in front of them.

Conclusion

The backend capability may be the same, but the consumer is not. A REST client follows integration logic written during development. An agent chooses operations at runtime. Directly wrapping every REST endpoint preserves an interface designed for a different consumer, so the MCP interface must carry more of the knowledge that code previously supplied.

This comparison is not exhaustive. Security, caching, and other operational dimensions introduce their own tradeoffs when the consumer is an agent. They deserve separate treatment and may become the subject of a future article.

From REST to MCP (1/2): Different Dimensions

Ibrahim Mohammed — Sun, 12 Jul 2026 12:07:57 +0000

Intro

An MCP server can look like another API layer: expose existing REST endpoints as tools and call it a day.

Both receive input, execute backend logic, and return a result. But they operate under different assumptions. This two-part series explains why directly wrapping REST APIs is a bad default. This first article covers the differences in their runtime environments. The second will discuss how those differences should affect MCP design (you already know how to design a good REST API). We can see those differences more clearly by comparing the two across several dimensions.

Dimensions

The consumer

With REST, developers encode control in application logic. The application knows when to call an endpoint, what arguments to send, and how to handle the response. Those decisions are made during development.

With MCP tools, much of that control moves to the AI agent. The model interprets the request, chooses a tool, constructs its arguments, evaluates the result, and decides what to do next. The harness can restrict it, but the model is still part of the control flow. A REST client already knows why it is making a call. An agent must first decide whether a tool is relevant at all. MCP tools

The context

A REST application can draw from application state, cookies, memory, and user input. Code written by a developer determines which parts become request parameters.

An agent can draw from the current request, conversation history, and previous tool results. The MCP server does not see this context automatically, but the model may turn parts of it into tool arguments at runtime.

The difference is who selects what reaches the backend: predetermined code or a model reasoning over a changing conversation.

The action model

REST APIs tend to expose focused, fine-grained operations that application code can compose. Keeping endpoints simple and stable limits regressions because a developer has already written and tested the workflow that connects them.

With MCP, the agent often constructs that workflow at runtime. Smaller operations give code more composability, but give an agent more choices, more intermediate results to interpret, and more opportunities to take a wrong turn. Copying a REST interface also copies assumptions about where the workflow lives and who composes it.

The failure model

A REST client can handle known status codes through explicit branches. Much of an error's meaning may exist only in the client code: the backend returns a code, and the application already knows the next step. Human-readable messages can become secondary output from the API. The backend and frontend developers agreed on this private language during their lunch break; the agent was not invited.

An agent must interpret the failure at runtime. It may need to change an argument, ask the user, choose another tool, or stop. If a wrapped API returns only a status code or internal identifier, the agent loses the knowledge that used to live in the REST client. Machine-readable codes still matter, but the model also needs detailed and actionable feedback. MCP tool error handling

The state model

REST is stateless, so each request contains the information needed to process it. The backend does not have to retain client session context, and requests remain independent from one another.

MCP has a connection lifecycle that starts with initialization and may include a server-side session. FastMCP(famous MCP server implementation) uses stateful sessions by default, retaining a context for each client between requests. It also supports a stateless mode that creates a fresh context for every request. MCP lifecycle, FastMCP session modes

UPDATE: MCP is becoming stateless

The cost model

In REST, a request and its response are normally processed once. They do not become persistent input that must be sent again with every later request. A REST response does its job and leaves; a retained tool result can move into the context window and keep charging rent. In common agent harnesses (like claude code), MCP tool inputs and outputs become part of conversation history. Every retained tool call takes space from the client's context window and is sent again on later model calls, so its cost compounds across the conversation. MCP client best practices

The trust boundary

A malicious REST API can return hostile data, but a conventional client normally processes it through predetermined code, in addition to another layer of security usually imposed by the user facing client like browsers.

An MCP tool interacts with a client whose control flow depends mostly on an LLM. Tool descriptions and results may influence what the model does next, opening the door to prompt injection, tool poisoning, context disclosure, or attempts to steer the agent toward another privileged tool.

The outcome also depends on the underlying model and the harness around it. This gives third-party MCP servers a larger client-side attack surface than ordinary API integrations. The MCP specification tells clients to treat descriptions of tool behavior as untrusted and validate results before passing them to the model. Security research has also found familiar implementation vulnerabilities in tested MCP servers. MCP tool security considerations, Equixly's MCP server research

Conclusion

The backend capability may be the same, but the consumer is not. A REST API client follows a workflow that is predetermined and coded by a developer. An agent has more work to do, it plans on the fly, and puts a novel effort on each turn to determine what to do, including choosing a tool, calling it correctly, and combining it with other tools to satisfy user needs.

Directly wrapping every REST endpoint preserves an interface designed for a different environment. If the consumer, context, action model, failure model, trust boundary, state model, and cost model are different, the interface design should probably be different too. That is the subject of part two.

Ultimate Guide to Coding Anarchy

Ibrahim Mohammed — Mon, 24 Jun 2024 04:24:17 +0000

Intro

Are you tired of writing boring, predictable code? Ready for a change? Well, buckle up! This guide provides you with 10 pieces of advice that will turn your codebase into a wild rollercoaster ride for anyone brave enough to maintain it! Warning: the advice in this article is sarcastic and should be reversed if you value your sanity (no shit, Sherlock).

1. Wet your code

Do you remember that smart code snippet that handles user authentication you copied from StackOverflow? I want you to copy/paste that snippet all over the project. Don't wrap it in a function that has a meaningful name that can be called whenever needed. Don't make your code DRY. Why? The main benefit is whenever you find a bug in this snippet, you will go through a long and amusing journey of updating this snippet everywhere it's written. So Much Fun. It's also another way to force you and your team to revise your code from time to time. Your team will surely appreciate that.

2. Write smart one-liners

Have you earned respect in your team yet? No? Here is what you need to do, fill the codebase with smart one-liners that only smart people like you can understand.
Let me show you an example I like a lot, the following dumb simple easy-to-understand code wastes 3 lines from our precious javascript files:

const obj = {};
If (x) { obj.x = x; }
If (y) { obj.y = y; }

Let's upgrade/optimize this code, for example, look at how compact and smart this alternative is:

const obj = { …(x && { x }), …(y && { y}) };

After you adapt yourself to this cryptic coding style, you will get 70x respected within your team, thank me later.

3. Be inconsistent and unconventional

As an extension to the last advice, I want you to break out of conventions and liberate yourself from chains. Some people whine too much about how your code should be consistent and follow agreed-upon conventions. Those "clean coders" police are holding you back. Examples:

Don't limit yourself to a single casing style within a project, make sure your functions have at least 2 casing styles like camelCase and snake_case.
Also, your function names shouldn't follow the same naming style. That's too dull, some function names should be verbs, some should be nouns, and some should be adverbs!
Always mix. Use a mix of callbacks, promises, async/await code. Use a mix of regular and arrow functions. Use mix classes and function constructors,...etc Within your programming language community, you would usually find one or two coding styling guides to chain you, ignore those guides, and Just Be Creative!

4. Don't comment your code

A wise man once said: "Good code does not need comments". That's 100% true. Don't insult yourself by putting comments in your good code. Do you remember that 200-line critical function that handles user payments in the application? this one particularly shouldn't be commented, and all variables in it should have 2 or 3 character names. This function is too critical, so it should be optimized more than anything else!

5. Nest your code

Have you ever heard of "Code Aesthetics"? It's about making our code beautiful and amusing to look at. One way to achieve this is by making 3+ nesting levels of your code blocks. For example, don't write dull code like that:

function checkDiscountEligibility(user) {
    if (!user) return console.log('User data is missing')
    if (!user.age) return console.log('User age is required')
    if (user.age < 18) return console.log('User must be at least 18 years old')
    if (!user.membership) return console.log('Membership status is required')
    if (user.membership !== 'gold') return console.log('Only gold members are eligible for a discount')
    applyDiscount(user)
}

Instead try writing a beautiful skewed pyramid shaped code like this:

function checkDiscountEligibility(user) {
    if (user) {
        if (user.age) {
            if (user.age >= 18) {
                if (user.membership) {
                    if (user.membership === 'gold') {
                        applyDiscount(user)
                    } else {
                        console.log('Only gold members can get discount')
                    }
                } else {
                    console.log('Membership status is required')
                }
            } else {
                console.log('User must be at least 18 years old')
            }
        } else {
            console.log('User age is required')
        }
    } else {
        console.log('User data is missing')
    }
}

6. Hardcode stuff

The more you Hardcode, the more Hardcore you are. Always hardcode configuration values, constants, and secrets(especially secrets) instead of grouping them in a config file or something as simple as a.env file. This will make your code comprehensive, have fewer dependencies, and also efficient(because no need to do additional lookups). You might ask what if we want to have different values for different environments? Simple do if conditions on the environment everywhere throughout the code. like this:

let lifeSecret = ""
if (process.env.NODE_ENV === 'development'){
    lifeSecret = "dev_blablabblalasec"
}
else if (process.env.NODE_ENV === 'production'){
    lifeSecret = "prod_blablahardcoresec"
}

Hint: Don't follow 12 factor app rule about organizing configs, those people are not efficient.

7. Don't handle errors

Errors are so overrated. Don't think too much about errors and handling them. Always focus on happy scenarios, because again, handling errors implicitly means that your code is error-prone, so please don't insult yourself. Some programming languages like Rust and Go deal with errors as first-class citizens to promote error handling explicitly. I'll give you examples but please this is only to show you how self in-confident those language developers are:
Go:

result, err := divide(4, 2) 
if err != nil { 
    fmt.Println("Error:", err) 
} else { 
    fmt.Println("Result:", result) 
}

Rust:

match read_file_to_string("example.txt") { 
    Ok(contents) => println!("File contents: {}", contents), 
    Err(e) => println!("Error reading file: {}", e) 
}

8. Depend on global variables

Maximize the dependence of global variables in your code. Why pass stuff as function arguments when you can make your entire codebase a creative playground?
For example:

const databaseConnection = require("database.js");
function fetchUserData(userId) { 
    databaseConnection.query(`SELECT * FROM users WHERE id = ${userId}`); 
}

See how we completely ignore dependency injection and save an additional parameter by pulling databaseConnection from thin air into the function? Some people would argue that this has multiple drawbacks, like:

It makes the code less predictable
It makes this function untestable
1. Preventing the application of the Unit of Work pattern to combine this function with others in a single transaction. But who needs predictability when you can embrace spontaneous creativity? And testing? Who has time for testing in 2024? We are developers, not testers! I'm 100% sure those critics don't do testing themselves. And Unit of Work pattern? Sounds like extra work to me! Just... ignore them and enjoy the freedom of your creative coding!

9. Mutate objects by passing them to magic functions

This is one of my favorites. I find a lot of creative people doing it without even reading my article.
Look at this dull immutable version:

const { originalDate } = require("./dates.js")
function addYear(date) {
  const newDate = new Date(date.getTime()); // cloning the date object
  newDate.setFullYear(newDate.getFullYear() + 1);
  return newDate;
}
console.log(originalDate); // 2024-06-24T00:00:00.000Z
let updatedDate = addYear(originalDate);
console.log(originalDate); // 2024-06-24T00:00:00.000Z (still as is)
console.log(updatedDate);  // 2025-06-24T00:00:00.000Z

Boring, right? Now, here's the "upgrade":

const { originalDate } = require("./dates.js")
function addYear(date) { 
    date.setFullYear(date.getFullYear() + 1); 
}
console.log(originalDate); // 2024-06-24T00:00:00.000Z
addYear(originalDate)
console.log(originalDate); // 2025-06-24T00:00:00.000Z (ta da!)

Isn't it thrilling? Now, anyone looking at originalDate will have no idea how and where it's value got mutated. Perfect!

10. Don't write secure code

A lot of paranoid devs worry too much about security, but this paranoia weakens your relationship with your app users. Learn to love your users, and you won't love them until you trust them completely by writing code like this:

app.post('/register', async (req, res) => { 
    let userData = { role: "user", ...req.body }; 
    await User.create(userData); 
    res.send('User created'); 
});

Now, imagine a request like this (but don't worry, your users would never do that of course):

`curl -X POST http://localhost:3000/register -H "Content-Type: application/json" -d '{"username": "hacker", "role": "admin"}'`

And this is what would be stored in our modern NoSQL store:

{ role: "admin", username: "hacker"}

See how effortless that is? Just merge everything from the request body into your sensitive data object. Who needs validation or sanitization? Trust your users—they always have your best interests at heart, right?
Always think good of your dear users. After all, what's the worst that could happen?

Conclusion

Congratulations! You've now learned the art of writing code that's sure to keep your fellow developers entertained and on their toes. By following these anti-patterns, you can inject a bit of excitement into your workday and create a codebase that's as unpredictable as it is "creative." Remember, consistency, maintainability, and security are just suggestions. True creativity lies in embracing the chaos and trusting that your users and colleagues will understand your genius. Happy coding!