HarnessAPI: Streaming API와 MCP 도구를 하나로 통합하는 Skill-First 프레임워크

Who Should Read

Claude, Cursor 같은 AI 에이전트에 도구를 제공하면서 동시에 REST API도 유지해야 하는 백엔드 개발자. FastAPI로 HTTP 서버 따로, MCP 서버 따로 관리하는 이중 유지보수에 지친 팀.

Core Mechanics

• 기존에는 같은 비즈니스 로직을 FastAPI HTTP 엔드포인트와 FastMCP 도구 등록, 두 군데에 따로 써야 했음. HarnessAPI는 handler.py + models.py 하나짜리 skill 폴더에서 둘 다 자동 생성.
• SSE(Server-Sent Events, 실시간 스트리밍 프로토콜) 스트리밍과 JSON 응답을 같은 엔드포인트에서 처리. 클라이언트가 Accept: application/json 헤더를 보내면 JSON, 아니면 SSE로 자동 분기.
• FastMCP의 타입 어노테이션 해석 버그 우회를 위해 exec()로 MCP 래퍼 함수를 동적으로 컴파일하는 기법 사용. Pydantic 모델을 함수의 __globals__에 직접 넣어서 해결.
• is_mcp = false 플래그 하나로 특정 skill을 MCP 레이어에서 숨기고 HTTP는 유지 가능. 관리용 내부 API를 에이전트 도구 목록에서 제외할 때 유용.
• harnessapi init --function f.py 명령어로 기존 Python 함수를 AST 파싱해서 Pydantic 모델과 skill 폴더를 자동 생성. 기존 코드베이스 마이그레이션 진입장벽 없음.
• enable_edit_endpoints=True 옵션으로 AI 코딩 에이전트가 서버 재시작 없이 핸들러 코드를 hot-swap 가능. 단, localhost에서만 작동하고 외부 노출 시 RuntimeError 발생.

Evidence

• 6개 skill 기준 프레임워크 보일러플레이트 코드가 수동 dual-stack(FastAPI 103줄 + FastMCP 67줄 = 170줄) 대비 HarnessAPI 44줄로 74% 감소.
• 수동 방식은 skill 수에 비례해 O(n)으로 코드가 늘어나지만, HarnessAPI는 O(1) 고정. 10개 skill 기준 수동은 약 283줄, HarnessAPI는 여전히 44줄 수준.
• agentskills.io 포맷의 skill 폴더 12개를 harnessapi init --skills-dir로 임포트했을 때 소스 변경 없이 전부 성공. SKILL.md, skill.toml 메타데이터 우선순위도 정확히 적용.

How to Apply

• 기존에 FastAPI + FastMCP를 따로 운영 중이라면 skill 폴더 구조(handler.py + models.py)로 리팩토링 후 pip install harnessapi로 단일 프로세스로 통합. 포트 2개 관리, 헬스체크 2개 운영 부담이 사라짐.
• Claude Desktop이나 Cursor에 도구를 등록하면서 동시에 웹 대시보드용 HTTP API도 제공해야 하는 경우, skill.toml에 is_mcp = true/false만 설정하면 노출 범위를 독립적으로 제어 가능.
• AI 코딩 에이전트(예: Cursor Agent)가 로컬 개발 중 핸들러 로직을 반복 수정해야 할 때, enable_edit_endpoints=True로 서버 켜두고 에이전트가 POST /skills/{name}/edit로 코드 교체하며 빠르게 이터레이션 가능.

Code Example

# 설치
pip install harnessapi

# skill 폴더 구조 생성
harnessapi init my-project

# skills/summarize/models.py
from harnessapi import SkillInput, SkillOutput

class Input(SkillInput):
    text: str
    max_length: int = 100

class Output(SkillOutput):
    summary: str

# skills/summarize/handler.py
from .models import Input, Output

async def handle(input: Input) -> Output:
    return Output(summary=input.text[:input.max_length])

# skills/summarize/skill.toml
[skill]
description = "텍스트를 요약합니다"
is_mcp = true
timeout_secs = 30

# main.py
from harnessapi import HarnessAPI

app = HarnessAPI(skills_dir="./skills")

# 실행: uvicorn main:app --reload
# → POST /skills/summarize (HTTP + SSE)
# → /mcp (MCP 도구 자동 등록)
# → /docs (Swagger UI 자동 생성)

Terminology

관련 논문

• ctx – 로컬 머신의 코딩 에이전트 히스토리를 검색하는 CLI 도구

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Model API 내부 협업으로 Frontier 모델을 이기는 방법 (vLLM Semantic Router)

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: 에이전틱 코딩을 위한 자기 개선형 오픈소스 모델

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Tool-Augmented Agent에서의 Entity Binding 실패 분석

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: 터미널에서 여러 AI Agent를 한 번에 관리하는 Agent Multiplexer

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: 스스로 Scaffold를 생성하는 Agentic Coding LLM

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

Related Resources

• https://github.com/edwinjosechittilappilly/harnessapi
• https://pypi.org/project/harnessapi/
• https://modelcontextprotocol.io