DEV Community: Stainless

MCP for your API

Min S Kim — Mon, 14 Apr 2025 21:17:35 +0000

Model Context Protocol (MCP) is an exciting new way to interact with APIs. Publishing an MCP server helps users interact directly with your API using natural language.

Our mission is to improve the API layer of the internet, and we’re excited to announce that you can now use Stainless to automatically generate MCP servers (for free) from your OpenAPI spec alongside your SDKs.

The MCP server generated by Stainless lives alongside your TypeScript SDK and is published as a separate npm package to minimize bundle sizes. It provides composable building blocks to create custom tools, controls to define exactly which parts of the API you want to expose, and an easy way for users to filter which tools they want to use.

For example, Modern Treasury’s new MCP server enables their customers to do one-off banking operations with simple language:

In the demo above, Claude finds an unpaid invoice, voids it, then creates a new one with a different discount using just conversational prompts and the list_invoices, update_invoice, and create_invoice tools.

Getting started

Adding MCP to your Stainless project is simple.

Navigate to your Stainless project dashboard, click Add SDKs, then select MCP Server from the options.

The generated MCP server can be tested immediately with MCP clients like Claude Desktop:

{
  "mcpServers": {
    "your_api": {
      "command": "npx",
      "args": ["-y", "your-api-mcp"],
      "env": {
        "YOUR_API_KEY": "your-api-key-here"
      }
    }
  }
}

Once configured, you can ask the LLM to interact with your API directly: "What products do we have available?" or "Create a new product called MCP Demo." The LLM will select the appropriate endpoint, pass the necessary parameters, and return the results.

By default, every endpoint is exposed (e.g., POST /products would become a create_product tool). You can fine-tune this by setting enable_all_resources: false in the mcp_server: section of your Stainless configuration and adding specific resources or endpoints with mcp: true.

Users can also tailor which tools they would like to expose to the model with options like --tool list_accounts, --resource accounts, or --operation read to reduce context size or prevent access to sensitive data.

Deploying remote MCP servers to Cloudflare Workers

The examples above are great for devs using local AI clients. But for non-devs using web apps, local MCP servers that rely on API keys for auth aren’t practical.

This is where remote MCP servers come in. It’s a newer part of the Model Context Protocol spec that enables OAuth-based authentication between clients and servers. While support is still nascent, you can use this today by deploying your Stainless-generated tools to a Cloudflare Worker.

The worker can handle OAuth with your existing provider or you can implement a custom flow directly in the worker. Check out the docs for more info.

MCP server generation is currently experimental and is free to all Stainless users.

Get started today at stainless.com/login.

Making Java enums forwards compatible

Tomer Aberbach — Tue, 11 Feb 2025 19:57:13 +0000

SDKs, like most downloaded software, quickly end up with client-server version skew. A great SDK gracefully handles skew by being forwards compatible with potential API changes.

This is especially important for Java SDKs, which could to be used in Android apps that users take a long time to update (if they update at all). An app shouldn’t start crashing just because it’s not using the latest SDK version!

It turns out Java enums are not trivially forwards compatible in this way.

An example API

Suppose we’re designing a Java SDK for a Pet Store API. We might end up with an enum for representing order status:

enum PetOrderStatus {
    PLACED,
    APPROVED,
    DELIVERED,
}

Users of our SDK would find this type more convenient than a String because it indicates exactly which statuses are possible. Users can even use “switch expressions” to ensure they handle all possible statuses:

String displayText = switch (petOrderStatus) {
    case PLACED -> "Your order was placed and is being reviewed.";
    case APPROVED -> "Your order was approved.";
    case DELIVERED -> "Your order was delivered!";
};

But how do we convert a string from the API response into an enum constant?

The most common way to parse a string into an enum constant is using the built-in Enum.valueOf method, which is automatically generated for every enum:

PetOrderStatus petOrderStatus =
    PetOrderStatus.valueOf(statusString.toUpperCase());

This works, but there are problems lurking.

An API change

Suppose one day our product manager pings us and says, “Customers want to know when their fluffball is on the way. Is that possible?”

“Sounds reasonable,” we think to ourselves. So we implement the feature, add "in_transit" as a possible order status in the API, and update our SDK and app like so:

 enum PetOrderStatus {
     PLACED,
     APPROVED,
+    IN_TRANSIT,
     DELIVERED,
 }

 String displayText = switch (petOrderStatus) {
     case PLACED -> "Your order was placed and is being reviewed.";
     case APPROVED -> "Your order was approved.";
+    case IN_TRANSIT -> "Your order is on the way!";
     case DELIVERED -> "Your order was delivered!";
 };

The feature works fine in our local environment so we decide to ship the changes.

Crashes galore

Almost immediately, we start getting crash reports for the Pet Store app. They all look like this:

Exception in thread "main" java.lang.IllegalArgumentException: No enum constant PetOrderStatus.IN_TRANSIT
    at java.base/java.lang.Enum.valueOf(Enum.java)
    at PetOrderStatus.valueOf(PetStoreApp.java)

But we did update the SDK enum with an IN_TRANSIT constant! What gives?

It turns out that all of the crashes are coming from customers who haven’t updated their app yet. In that previous version, Enum.valueOf throws an IllegalArgumentException when the input doesn’t match any known enum constant.

The API started including "in_transit" in responses, but almost all customers are still using the previous SDK version!

The solution

So what’s an SDK engineer to do? How could we have avoided this incident?

One option is to make the type Optional<PetOrderStatus> instead of just PetOrderStatus, which would allow us to return Optional.empty() when the value is not a known constant. This isn’t ideal for a few reasons:

We can’t access the raw API value in the Optional.empty() case.
Optional.empty() looks like it means there’s no order status, but that’s not what we’re trying to convey.
What if we want to represent the concept of “no order status” in the future? We would no longer be able to use Optional.empty() for that!¹

A more robust solution would be to store the raw API value and provide access to both the raw value and an enum representation of it.

We might end up with a class that looks like this:

public final class PetOrderStatus {
    private final String value;

    private PetOrderStatus(String value) {
        this.value = value;
    }

    /** Used to "parse" the API value. */
    public static PetOrderStatus of(String value) {
        return new PetOrderStatus(value);
    }

    /** Returns the raw API value. */
    public String _value() {
        return value;
    }

    /** Returns an enum containing known order statuses. */
    public Value value() {
        return switch (value) {
            case "placed" -> Value.PLACED;
            case "approved" -> Value.APPROVED;
            case "delivered" -> Value.DELIVERED;
            default -> Value._UNKNOWN;
        };
    }

    public enum Value {
        PLACED,
        APPROVED,
        DELIVERED,
        /** The order status is not known to this SDK version. */
        _UNKNOWN,
    }
}

And our SDK users could use the class like so:

String displayText = switch (petOrderStatus.value()) {
    case PLACED -> "Your order was placed and is being reviewed.";
    case APPROVED -> "Your order was approved.";
    case DELIVERED -> "Your order was delivered!";
    // Fallback for new order statuses not known to this SDK version.
    case _UNKNOWN -> "Your order status is: " + petOrderStatus._value();
};

This design has several benefits:

We still get all the benefits of enums, including exhaustiveness checks that now require us to handle the unknown status case.
We can still use the raw API value in the unknown status case.

An API change: part 2

With this new SDK design, our app wouldn’t have started crashing after the API change. Instead, previous app versions would have displayed the following message:

Your order status is: in_transit

And if we had made the following change to our SDK and app:

 public final class PetOrderStatus {
     // ...

     public Value value() {
         return switch (value) {
             case "placed" -> Value.PLACED;
             case "approved" -> Value.APPROVED;
+            case "in_transit" -> Value.IN_TRANSIT; 
             case "delivered" -> Value.DELIVERED;
             default -> Value._UNKNOWN;
         };
     }

     public enum Value {
         PLACED,
         APPROVED,
+        IN_TRANSIT,
         DELIVERED,
         /** The order status is not known to this SDK version. */
         _UNKNOWN,
     }
 }

 String displayText = switch (petOrderStatus.value()) {
     case PLACED -> "Your order was placed and is being reviewed.";
     case APPROVED -> "Your order was approved.";
+    case IN_TRANSIT -> "Your order is on the way!";
     case DELIVERED -> "Your order was delivered!";
     // Fallback for new order statuses not known to this SDK version.
     case _UNKNOWN -> "Your order status is: " + petOrderStatus._value();
 };

Then customers would get better display text the next time they update.

Try Stainless today.

Yes, we could do Optional<Optional<PetOrderStatus>>, but good luck getting that through design review. ↩