November 2025 Summaries

The text explores two architectural options, Retrieval-Augmented Generation (RAG) and Model Context Protocol (MCP), for enhancing large language models (LLMs) with external information, particularly when the models lack up-to-date or domain-specific data. RAG is an architecture pattern that excels at semantic search by embedding documents into vectors for efficient retrieval based on user queries, making it highly effective for static content like documentation. MCP, on the other hand, standardizes how LLMs connect to external tools and data sources, proving advantageous for dynamic data that changes frequently, such as live inventory or product information. The text details how each approach handles the task of providing an LLM with new features from Django 5.2’s documentation, highlighting the token efficiency and response time benefits of RAG due to its semantic vectorization. While RAG provides more relevant context with fewer resources, MCP allows for real-time data access and can execute actions, making it suitable for dynamic structured data. The document suggests that both RAG and MCP can be used in tandem, with MCP servers facilitating RAG queries, to leverage the strengths of both methods, enhancing the capabilities of AI systems in different scenarios.

The blog post evaluates five popular documentation vendors—Mintlify, Scalar, Bump, ReadMe, and Redocly—focusing on their unique features, ease of use, theming and customization options, developer experience, and support and pricing structures. Scalar stands out for its standalone API client and seamless integration with various frameworks, while Mintlify excels in customization and is particularly suited for narrative-based documentation. Bump is noted for its performance with large API specifications, making it ideal for complex APIs, whereas ReadMe is designed for non-technical teams, offering a user-friendly, web-based experience at the cost of advanced automation features. Redocly is praised for its deep integration across API development ecosystems but is seen as less visually appealing compared to newer platforms. Each tool has distinct advantages depending on the specific needs and priorities of development teams, from interactive features and customization to ease of use for non-technical users.

Terraform providers generated with Speakeasy now include automatic polling support for API operations that perform background processing, eliminating the need for manual waiter logic when resources need time to reach a desired state. This feature addresses the common pattern of long-running requests in infrastructure APIs, where operations such as creating database instances or spinning up compute resources are performed asynchronously. The polling support utilizes the x-speakeasy-polling OpenAPI extension, which defines success and failure criteria, as well as timing configurations, for these operations, allowing Terraform resources to automatically handle state transitions during the resource lifecycle, including create, update, delete, and read/refresh phases. This integration simplifies Terraform provider development by removing the need for custom polling logic, ensuring consistent behavior across resources, and providing robust error handling and a seamless user experience.

Building the Gram codebase with a focus on ease of use for both developers and AI agents has inadvertently enhanced its AI-friendliness, as the principles of clarity and discoverability benefit both groups. The project employs a contract-first design approach with extensive code generation using tools like Goa, SQLC, Speakeasy, and Atlas, facilitating tasks like API endpoint creation and database migrations. The monorepo structure of Gram consolidates all components, such as the server and web app, which allows seamless interaction and reduces context switching. The use of a polyglot development environment manager, Mise, organizes and simplifies tasks, making it easy for agents to execute commands and ensure a smooth development setup through automation. While AI agents excel at repetitive tasks and pattern recognition, developers focus on design and complex problem-solving, leveraging AI for efficiency in routine operations. This structure not only streamlines AI integration but also accelerates onboarding for new team members and enhances overall codebase productivity.

Chase Crumbaugh discusses the advancements in the Model Context Protocol (MCP), particularly focusing on reducing token usage through the introduction of Dynamic Toolsets. Speakeasy's refined Dynamic Toolset implementation combines progressive and semantic search methods to effectively minimize token consumption by 96% for inputs and 90% for total usage, enabling the handling of hundreds of tools without overwhelming language model context windows. This new approach features three core tools—search_tools, describe_tools, and execute_tool—that together optimize token efficiency and maintain a 100% success rate across diverse tasks. Despite requiring more tool calls and slightly increasing execution time, Dynamic Toolsets provide a scalable, cost-effective solution to the challenges of building AI agents capable of interfacing with large toolsets, demonstrating the flexibility and adaptability of MCP in addressing real-world AI system needs.

Gram Functions, a TypeScript-native framework, simplifies building agent tools by allowing developers to define tool logic in code, eliminating the need to understand MCP protocol details or manage infrastructure. This framework, part of the MCP cloud platform Gram, enables rapid deployment of production-ready MCP servers with built-in enterprise-level performance, observability, and security. Developers can define tools using an intuitive API with four components—name, description, inputSchema, and execute—and deploy them in a serverless environment, integrating various functions and OpenAPI into a single MCP server. Gram Functions enhances developer experience by focusing on core MCP building blocks, allowing complex workflows that involve API calls, database queries, and business logic to be encoded once and used repeatedly, improving reliability and reducing failure rates. The framework is available to users on all tiers, including free, and supports integration with MCP-compatible platforms, with future expansions planned to include support for ChatGPT Apps and toolset staging capabilities.

Chase Crumbaugh's article discusses a significant update to the Gram OSS repository, which introduces dynamic toolsets to manage token usage efficiently on MCP servers. Traditional static toolsets load all tools into an AI agent's context window at once, leading to excessive token consumption, particularly problematic as toolsets grow in size. To address this, two dynamic approaches, progressive and semantic search, are proposed. Progressive search uses hierarchical meta-tools to discover and execute necessary tools, while semantic search employs embeddings for faster, natural language-driven tool discovery. Both methods dramatically reduce token use and maintain consistent performance across varying toolset sizes. Initial tests show that dynamic toolsets can handle complex tasks more efficiently than static ones, offering scalable, cost-effective solutions for large APIs. The implementation involves exposing meta-tools for discovery and deferring detailed tool schema loading until explicitly required, enhancing efficiency. While still experimental, dynamic toolsets promise better scalability and predictable costs, making them valuable for large API operations without breaching context window limits.

Speakeasy has integrated support for Zod v4 mini into its TypeScript SDKs, offering a significant reduction in bundle size by approximately 10% while preserving runtime type safety. Zod addresses the lack of runtime type safety in TypeScript by validating API responses, preventing errors caused by type mismatches. The new Zod v4 mini variant improves tree-shaking capabilities through its standalone function API, reducing its footprint to about half the size of its predecessor, Zod v3, and enhancing performance with faster parsing capabilities. These internal updates allow SDK users to continue utilizing the familiar class-based interface without requiring changes on their part, benefiting from smaller bundles and faster runtime validation. The transition to Zod v4 mini is optional and can be enabled through the gen.yaml configuration file, although some edge cases, such as compatibility issues with MCP servers, may necessitate retaining Zod v3. This update aligns with Speakeasy's commitment to developing adaptable TypeScript SDKs for diverse environments, including Node.js servers, browser frontends, and mobile applications.

The blog post offers a comprehensive comparison between Gram and FastMCP, two platforms designed for building and deploying Model Context Protocol (MCP) servers. Gram is an open-source, TypeScript-based platform that emphasizes protocol-agnostic flexibility, allowing tools to adapt as ecosystems evolve without rewriting core logic. It offers a serverless infrastructure, automatic OpenAPI synchronization, and managed authentication services, making it suitable for teams looking to quickly deploy and maintain MCP servers with minimal boilerplate. In contrast, FastMCP, a Python-specific framework, provides a more MCP-specific and control-oriented approach, requiring significant engineering investment for customized authentication and server management. It operates on a server-based architecture, offering developers complete control over MCP-specific features at the cost of greater development and maintenance efforts. The choice between the two platforms depends on the team's language preference, desired level of control, and resource availability for infrastructure management.

In response to recent supply chain attacks, the npm ecosystem has implemented significant security changes, particularly concerning authentication tokens. Starting in October, newly created write-enabled granular access tokens will expire after seven days by default, with a maximum lifespan of 90 days. Additionally, npm will revoke all existing legacy tokens and disable their future generation. To enhance security and simplify the publishing process, transitioning to Trusted Publishing using OpenID Connect (OIDC) is recommended, as it eliminates token rotation and provides automatic provenance attestation. The process involves updating GitHub workflow permissions and configuring trusted publishing settings on npm, which, despite requiring initial setup, promises long-term benefits in terms of security and maintenance.

AI agents are increasingly integral in software interactions, necessitating a standardized method to interact with APIs, which is where the Model Context Protocol (MCP) comes into play. Introduced by Anthropic in 2024, MCP provides a universal standard for AI agents to connect to APIs and data sources, transforming OpenAPI-documented endpoints into discoverable tools for these agents. Several tools, including Speakeasy, Gram, FastMCP, and openapi-mcp-generator, enable automatic generation of MCP servers from OpenAPI documents, each offering varying levels of customization, hosting models, and automation to suit different needs. While Speakeasy and openapi-mcp-generator support self-hosting with extensive code control, platforms like Gram and FastMCP Cloud offer managed hosting options for ease of use and quick deployment. These tools convert OpenAPI specifications into MCP server implementations, simplifying the process of making APIs accessible to AI agents while ensuring consistency and eliminating the redundant effort of maintaining separate specifications. By adopting these solutions, teams can enhance their APIs' readiness for AI-driven interactions, optimizing their OpenAPI documents for clarity and completeness to better serve AI agents' needs.