HarnessAPI: A Skill-First Framework for Unified Streaming APIs and MCP Tools

2026-05-21

AI Summary

This work addresses the redundancy and inconsistency arising from maintaining separate HTTP endpoints and Model Context Protocol (MCP) tool registrations in current large language model (LLM) tool development, which leads to duplicated business logic and boilerplate code. To resolve this, the authors propose a skill-centric unified framework that treats the skill registry as the single source of truth. Leveraging Pydantic type annotations and content negotiation, the framework dynamically generates FastAPI endpoints with Server-Sent Events (SSE) streaming support, interactive OpenAPI documentation, and zero-configuration MCP tools. This approach ensures seamless compatibility with both streaming and non-streaming clients while preserving type consistency. Evaluation across six representative skills demonstrates a 74% reduction in boilerplate code compared to manual dual-stack implementations, without sacrificing any capabilities of the FastAPI ecosystem.

Abstract

Every Python function deployed as an LLM tool must today exist in two forms: an HTTP endpoint for human-facing clients and CI pipelines, and an MCP tool registration for agent runtimes such as Claude and Cursor. These representations share business logic yet diverge in all the surrounding machinery (routing, validation, serialisation, streaming, and schema maintenance), and they drift apart as the underlying code evolves. We present HarnessAPI, a Python framework that eliminates this duplication by treating a typed skill folder as the single source of truth. From one handler.py plus Pydantic schemas, the framework automatically derives a streaming HTTP endpoint with Server-Sent Events, an interactive OpenAPI/Swagger UI, and a zero-configuration MCP tool, all served from a single process. Dual-mode content negotiation lets the same handler serve SSE-streaming and JSON-returning clients with no handler changes. A dynamic code-generation mechanism ensures Pydantic type annotations propagate correctly to FastMCP's inspection layer, resolving a technical limitation that prevents naive closure-based registration. Measured across six representative skills using cloc, HarnessAPI reduces framework-facing boilerplate by 74% compared with a manually maintained dual-stack implementation (FastAPI server + FastMCP server). HarnessAPI subclasses FastAPI, inheriting its full middleware, dependency-injection, and deployment ecosystem. It is available at https://github.com/edwinjosechittilappilly/harnessapi and on PyPI (pip install harnessapi)

Problem

• LLM tools
• API duplication
• MCP
• streaming APIs
• code maintenance

Innovation

• Skill-First Framework
• Unified Streaming API
• MCP Tool Integration
• Pydantic Type Propagation
• Server-Sent Events (SSE)