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

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)

• The paper introduces a skill-first architecture that replaces dual registrations with a unified skills folder, ensuring Pydantic-based schema consistency across HTTP and MCP endpoints.
• It leverages FastAPI and FastMCP to offer dual-mode content negotiation for SSE streaming and JSON responses, maintaining transport-agnostic execution for diverse applications.
• Empirical evaluation demonstrates a 74% reduction in framework boilerplate, enabling constant-time scalability and significantly lowering maintenance overhead for LLM agent tools.

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

Motivation and Background

In contemporary LLM agent architectures, tool invocation is the canonical pathway for agents to interact with external systems. Despite the centrality of this pattern—spanning ReAct, AutoGen, and others—the practicalities of tool deployment remain fragmented. Agent runtimes and CI pipelines leverage HTTP REST endpoints, while agent frameworks increasingly adopt the Model Context Protocol (MCP) as a standard for tool discovery and execution. This bifurcation imposes a maintenance burden: for every tool, developers must create and synchronize two distinct registration pathways, each with divergent schema definitions and lifecycle models, leading to drift and reliability hazards, as previously documented in the literature [Patil et al., (Patil et al., 2023)] [Qin et al., (Qin et al., 2023)].

Approximately 88.6% of MCP servers are backed by REST endpoints, reinforcing the pervasiveness of dual-stack deployments [Mastouri et al., (Mastouri et al., 21 Jul 2025)]. Current tool abstractions in frameworks like FastAPI (HTTP-first) and FastMCP (MCP-first) fail to treat the "skill" as the core unit of abstraction, forcing manual synchronization and undermining type safety and schema correctness as system complexity grows.

The Skill-First Architecture

HarnessAPI introduces a strict inversion: the typed skill folder, not the route or tool decorator, is the authoritative source of truth. Each skill is a directory encapsulating the handler logic and Pydantic-defined input/output schemas, which HarnessAPI automatically projects into both an HTTP endpoint and an MCP registration. This guarantees transport-level schema consistency by construction, eliminating all sources of manual drift. Dual-mode content negotiation at the HTTP layer enables transparent support for both Server-Sent Events (SSE) streaming (optimized for interactive applications) and JSON batch responses, with the same handler logic agnostic to execution context.

The architecture leverages the FastAPI middleware ecosystem and runtime, mounting FastMCP as an ASGI sub-application. This single-process arrangement unifies deployment and streamlines lifecycle management without sacrificing the robustness or extensibility of either underlying system.

Design and Implementation

Skill Anatomy and Discovery

A HarnessAPI skill folder minimally comprises handler.py and models.py. The handler is asynchronous and can be streaming (yield) or non-streaming (return). Pydantic type annotations are leveraged for input/output validation and for schema derivation in both OpenAPI and MCP tool registrations. Optional files (skill.toml, SKILL.md, defaults/, and examples/) support metadata, exposure configuration, and documentation.

A deterministic discovery pipeline walks the skills directory, loads each skill in a synthetic namespace to avoid module naming collisions, and merges metadata from all available sources, prioritizing explicitness (TOML > Markdown front-matter > docstring > folder name).

Unified Streaming and Content Negotiation

Handlers supporting both batch and streaming output variants are routed based on Accept headers. SSE streams are the default for interactive clients, minimizing latency per [Agrawal et al., (Agrawal et al., 2024)]. JSON mode is seamlessly available for batch or CI consumers. Handlers remain transport-agnostic, simplifying tool development.

Dynamic MCP Wrapper Generation

FastMCP's schema-inspection approach necessitates that input/output type declarations be discoverable in the function’s global namespace. HarnessAPI circumvents Python closure limitations by dynamically compiling MCP wrappers in a controlled, dedicated namespace with explicit model injection. This technical approach, while relying on exec, is strictly scoped and slated for eventual deprecation pending FastMCP’s adoption of explicit schema APIs.

Handler Hot-Swapping and CLI Tooling

For local iteration, handlers can be hot-swapped at runtime via a dedicated endpoint, guarded to prevent remote code execution vulnerabilities in production. The accompanying CLI generates compliant skill scaffolds from existing codebases or skill directories, lowering barriers to adoption for legacy tools.

Empirical Evaluation

Boilerplate Reduction

Across six representative skills—Echo, Greet, Summarize, VectorNorm, Classify, and Translate—HarnessAPI achieves a 74% reduction in framework-facing boilerplate compared to manual dual-stack (FastAPI+FastMCP) implementations. The observed scaling property is $O(1)$ for HarnessAPI versus $O(n)$ for manual setups as the number of skills increases. Framework logic remains static as skills are added; legacy approaches accumulate complexity linearly with each new tool.

Feature Parity and Compatibility

HarnessAPI provides native support for all features necessary for agent-facing tool deployments: HTTP endpoint exposure, MCP registration, OpenAPI/Swagger UI generation, SSE streaming, JSON fallback, per-skill timeouts, skill-level MCP disabling, agentskills.io compatibility, and single-process deployment. All features are available out-of-the-box, contrasting with manual layering or auxiliary libraries in baseline frameworks. Direct compatibility was demonstrated via the import and exposure of twelve agentskills.io-formatted skills without code modifications.

Security and Limitations

While the framework’s entrypoint and multiplexed registration strategy eliminate nearly all avenues for schema drift, some caution is warranted:

• The enable_edit_endpoints option (handler hot-swap) enables arbitrary code execution and is strictly limited to local/testing contexts, enforced programmatically.
• The exec-based dynamic wrapper required by FastMCP’s schema resolver is narrowly scoped but flagged by static analysis; migration to explicit schema APIs is planned.
• Deeply nested Pydantic union models may expose rare edge cases due to FastMCP’s current type system; these are tracked in the open-source repository.
• Authentication and access control are presently inherited from FastAPI. MCP endpoints lack fine-grained, per-tool ACLs, necessitating upstream proxying for secure multi-tenant deployments.

No direct performance benchmarks are reported; the authors defer to existing literature confirming FastAPI's ASGI throughput dominance under asynchronous workloads [Alaanzy & Yeshpatov, ICECCO 2026].

Implications and Future Directions

HarnessAPI’s skill-first model streamlines tool deployment for LLM agent ecosystems and may serve as a basis for further protocol unification. By extricating the developer from dual-registration and synchronization tasks, it substantially lowers operational complexity and fosters more scalable tool development practices. Theoretical implications include a move toward schema invariance by construction, while practically, the resulting interface enables rapid skill onboarding, self-documentation, and reduced incident surface from manual drift.

Anticipated directions for future work include:

• Per-skill authentication control with decoupled HTTP/MCP visibility.
• File-system watching for hot skill reloading without server restarts.
• Migration to FastMCP’s explicit schema APIs, removing non-standard wrapper strategies.
• Integration with skills registries providing versioned discoverability and provenance for distributed agent ecosystems.

Conclusion

HarnessAPI delivers a structurally enforced, skill-first paradigm for unified agent tool deployment, resolving a core pain point in contemporary LLM operational infrastructure. Its constant-time framework complexity, empirical reduction in maintenance overhead, and seamless multi-protocol projection redefine best practices for tool exposure in AI agent development, setting a strong precedent for future unification efforts in protocol-driven agent tooling.

Reference: "HarnessAPI: A Skill-First Framework for Unified Streaming APIs and MCP Tools" (2605.22733)