Skip to main content

Tag · 30 essays

API design

Writing tagged "API design".

← All writing

Building MCP Profile Hub part 2, one MCP server is the wrong abstraction

This article argues that a single, monolithic MCP server per platform is the wrong abstraction, especially for complex systems like Contentstack. Instead, it introduces managed profiles as the right unit of configuration, aligned to jobs, teams, or access boundaries rather than product catalogs. Each managed profile bundles a curated set of tools, Automations, and agents, enriched with account context, while still respecting individual user identities and permissions. Profiles can only narrow what a user can do, never expand their underlying platform permissions. This makes configurations easier to reason about, review, audit, and replicate across environments, and offers a scalable pattern for enterprise platforms with many roles and capabilities.

  • Composable architecture
  • AI engineering
  • API design
  • Frontend

Building MCP Profile Hub, part 1: Stop making the agent ask

Introducing MCP Profile Hub. I explain why enriching tool definitions with tenant-specific context dramatically improves agent performance. Instead of exposing generic CMS tools that force models to discover content types, environments, locales, and branches through multiple lookup calls, Profile Hub injects real account data directly into JSON Schemas as enums, defaults, and descriptions. This reduces tool calls, latency, and reasoning tokens while avoiding misleading examples and invalid defaults. The piece also covers the production engineering behind enrichment, how Automations and Agent OS agents are exposed as high-level deterministic tools, and why reusable HTTP-based tool definitions let teams run their own MCP runtimes. The core takeaway is that fewer, richer, context-aware tools beat large generic catalogs for real-world agent workflows.

  • Composable architecture
  • AI engineering
  • API design
  • Frontend

The Doer Economy - we are killing the translator class

This article argues that AI is collapsing the distance between vision and execution, ushering in a Doer Economy where the primary winners are those who can both imagine and build. The traditional corporate stack of translators (product managers, marketers, and multiple layers of management) is shrinking because executional tasks are increasingly handled by AI. Founders and CEOs are moving closer to product, validating ideas directly with AI-generated scaffolds and modern SaaS primitives. For individuals, the value has shifted from narrow, ticket-driven skills to end-to-end ownership, product thinking, and understanding users. The future belongs to people who ship, iterate quickly, and leverage AI and SaaS platforms to focus on business logic and user experience, rather than those who only manage the builders.

  • Composable architecture
  • AI engineering
  • API design
  • Frontend

The tool catalog is the product

We exposed Contentstack MCP tool definitions through a server endpoint as JSON. That sounds small, but it changes the product shape. The hosted MCP server becomes one official implementation of a reusable tool catalog, while developers can build their own MCPs with their own auth, hosting, filtering, and governance. This is what AI-first developer tooling should feel like: polished defaults on top of portable primitives.

  • AI engineering
  • API design
  • Developer experience

AI will not live in one place, but trust has to

Enterprise AI is spreading into every tool where work happens, from IDE agents to browser assistants, but governance, spend control, and brand safety are lagging behind. This article explains a two-layer architecture for solving that tension. Off-platform AI, powered by APIs, MCP, and agent skills, acts as the reach layer that lets developers and teams experiment, prototype, and orchestrate across systems from within their preferred tools. On-platform AI, delivered through Agent OS, Polaris, and AI Credits, is the trust layer that handles permissions, spend visibility, brand context, review workflows, and auditability. Rather than choosing between open access and tight governance, enterprises should use both layers together so external AI gathers context while governed on-platform capabilities execute business-critical work safely.

  • Composable architecture
  • AI engineering
  • API design
  • Content ops

The future of software is bespoke

This article argues that generic SaaS dashboards are a legacy compromise from a time when custom software was expensive and slow to build. With modern APIs, solid SDKs, scaffolding, and AI-assisted development, teams can now create focused, bespoke interfaces in days that match their exact workflows, instead of fighting through one-size-fits-all UIs. The platform should be treated as the engine providing authentication, permissions, content modeling, and governance, while product teams own the experience layer tailored to their people. The piece also examines trade-offs like maintenance burden, skills gaps, and fragility, and explains how good scaffolding, community patterns, and developer education can mitigate these risks and make custom tooling a pragmatic default.

  • Composable architecture
  • CMS
  • API design
  • Frontend

MCP fragmentation, context efficiency, and the rise of curated skills

The Model Context Protocol (MCP) was supposed to be a universal way to connect AI models to tools, but in practice it is fragmenting fast across vendors and implementations. Tool catalogs are extremely context-hungry, making naive MCP setups expensive, slow, and unreliable, especially with cheaper models. Developers are compensating with application-layer tricks like curated tool subsets, OAuth-based selection, Claude Skills style abstractions, and wrapping deterministic automation platforms such as Contentstack Automate. These patterns improve cost, reliability, and debuggability but highlight protocol-level gaps in context efficiency, determinism, and interoperability. The ecosystem is replaying past standards wars, and no clear winner is visible yet. The pragmatic move is to design flexible systems that can adapt when consolidation and better standards eventually emerge.

  • Composable architecture
  • AI engineering
  • API design
  • Performance

AI integrations expose platforms without headless DNA

AI exposes which platforms were truly built API first and which ones only marketed it. As brands move into AI native workflows, the only viable path is a system that treats agents, events, and automation as composable building blocks. Contentstack's agentOS shows what happens when you start with API first DNA instead of bolting AI onto a monolithic core. This piece explains why AI native composability is the next logical layer of MACH and why brands should judge vendors by the architecture of their agents, not the slideware that surrounds them.

  • Composable architecture
  • AI engineering
  • CMS
  • API design

The MACH monolith in 2026

The 2022 diagnosis was right. Composable architectures need orchestration or they collapse. But the form factor was wrong. Teams rejected standalone orchestration layers as too heavy, another vendor, contract, and critical path. The 2026 reality is platforms that integrate orchestration directly, staying API-first and modular while providing built-in coordination. The shift isn't about more tools, but smarter platforms that reduce complexity fatigue without losing flexibility.

  • Composable architecture
  • AI engineering
  • CMS
  • API design

It's time to think of LLMs as having abilities, not protocols

TL;DR Don't over-engineer standards around protocols. Instead, treat your large-language-model as a toolbox of abilities (like search, translate, query, generate) that you plug into your system. By thinking of LLMs as modular and composable abilities rather than monolithic protocols, AI becomes accessible, practical and aligned with how engineering and product teams already build.

  • Composable architecture
  • AI engineering
  • CMS
  • API design

SDKs are everywhere. But should you use them?

Explore the significance of Software Development Toolkits (SDKs) in modern development, their advantages, and when you might want to skip them. From enhancing productivity to integrating complex functionalities seamlessly, the right SDK can accelerate your projects. But what about GraphQL-based systems or the flexibility of headless architectures? Dive into the pros and cons to make an informed decision.

  • Composable architecture
  • CMS
  • API design
  • Performance