HarnessAPI: A New Framework Designed to Unify AI Agent Tools and Traditional API Development
A preprint paper published in May 2026, titled “HARNESSAPI: A SKILL-FIRST FRAMEWORK FOR UNIFIED STREAMING APIS AND MCP TOOLS,” introduces a Python framework called HarnessAPI. Proposed by Edwin Jose from Western Michigan University, the framework aims to solve a core engineering pain point in current Large Language Model (LLM) application development: the code redundancy and interface inconsistency caused by separately maintaining traditional HTTP APIs and AI agent tools (Tools) for the same business logic.
The ‘Dual Maintenance’ Dilemma in AI Development
As the need for LLMs to interact with the external world grows, “Tool Use” has become a core capability of AI Agents. To standardize this process, companies like Anthropic have introduced the Model Context Protocol (MCP), which provides a standard for how AI discovers and uses external tools. However, this advancement has brought new challenges for software developers.
Currently, for a Python function to serve an AI agent, it typically needs to exist in two forms:
- HTTP API: Called by traditional web clients, mobile apps, or automated testing workflows, usually built on frameworks like FastAPI.
- MCP Tool: Designed specifically for AI agents, it must be registered according to the MCP specification so that the AI can understand its functionality, inputs, and outputs.
Although these two forms share the same core business logic, their boilerplate code (such as route definitions, data validation, and format descriptions) is completely different. Developers need to write and maintain two separate sets of interface code for the same function. This not only increases the workload but also easily leads to “Schema Staleness”—a problem where the definitions of the two interfaces diverge over version iterations. This inconsistency is a key reason why AI agents “hallucinate” and call tools incorrectly.
HarnessAPI’s Core Design: The ‘Skill-First’ Architecture
To fundamentally solve the above problems, HarnessAPI proposes a “Skill-First” architectural paradigm, which subverts the traditional “Route-first” development model.
In the traditional model, a developer first defines the API’s URL path and then binds the business logic to it. In HarnessAPI, the only core focus for the developer is the “Skill.” A skill is organized within a dedicated “Skill folder,” which becomes the Single Source of Truth describing that business capability.
A standard skill folder contains two core files:
models.py: Defines the input and output data structures of the skill using standard libraries like Pydantic. This file serves as the unified data contract, from which HarnessAPI generates both the data validation rules for the HTTP API and the schema definitions for the MCP tool.handler.py: Contains the Python code that implements the skill’s core logic. All logic, whether returning complete data or generating results progressively via streaming, is centralized here.
When the application starts, the HarnessAPI framework automatically scans all skill folders and, based on their definitions, simultaneously generates fully functional HTTP API endpoints and an MCP-compliant AI tool within the same process. This completely eliminates the need to manually maintain two separate interfaces.
Key Technical Implementations and Features
HarnessAPI achieves its core value through several clever technical designs.
Consistency by Construction
Since both the HTTP API and the MCP tool are derived from the same models.py file, they achieve “Correctness by construction” at the data structure level. This means any modification to the data model is automatically synchronized to both interfaces, architecturally eliminating the risk of AI call failures caused by inconsistent interface definitions.
Dual-Mode Streaming
To handle the streaming nature of large model outputs, HarnessAPI has a built-in intelligent “dual-mode content negotiation” mechanism. Developers only need to write the core logic once, and the framework determines the response method based on the client’s request type (judged by HTTP headers):
- Streaming Response (SSE): If the client requests streaming data (e.g., an interactive chat interface), the framework transmits the generated content in real-time as Server-Sent Events.
- Aggregated Response (JSON): If the client needs the complete result at once (e.g., a background batch processing task), the framework will internally buffer all streamed fragments and return them as a single JSON object after generation is complete.
Single-Process Deployment and Lifecycle Fusion
HarnessAPI cleverly merges the FastAPI-based HTTP service and the FastMCP-based tool service into a single Uvicorn worker process. The paper’s author uses “nested context managers” to seamlessly integrate the startup, runtime, and shutdown lifecycles of both services. This achieves a single-process deployment that simplifies operational complexity and saves server resources.
Quantified Benefits and Engineering Value
The paper quantitatively evaluates the benefits of HarnessAPI through a controlled experiment involving 6 typical skills (such as text summarization and translation).
- Code Reduction: Compared to the traditional method of manually maintaining two interfaces (requiring 170 lines of boilerplate code), HarnessAPI requires only 44 lines. This represents a 74% reduction in framework boilerplate code. More importantly, the complexity of its framework code transitions from O(n) to O(1), meaning that adding new skills adds almost no extra framework configuration code.
- Development Efficiency: The framework supports a “Hot-Swap” feature in the local development environment. When a developer (or a developer-assisting AI) modifies the skill logic, the service can apply updates without a restart, significantly accelerating the iteration speed of AI applications.
In conclusion, HarnessAPI is not a new AI algorithm but a profound software engineering refactoring. Through its ‘Skill-First’ architectural philosophy, it provides an elegant solution for AI application development, freeing developers from tedious interface maintenance to focus on implementing core business logic. This, in turn, elevates the stability and maintainability of AI agent applications to a new level.
