# harnessapi

> Skill-first Python framework that turns a skill folder into a streaming HTTP API and an MCP tool — simultaneously, with no routes, no decorators, and no separate server to maintain.

harnessapi is a Python framework (MIT license, Python 3.11+) built on FastAPI and FastMCP. Write a skill folder with two required files (models.py for Pydantic I/O, handler.py for async logic) and optionally a skill.toml for metadata. harnessapi discovers it at startup and registers it as a POST /skills/{name} HTTP endpoint, an MCP tool at /mcp, and an entry in the Swagger UI at /docs — all three simultaneously.

Streaming is built in: use `return` for a single response, `yield` for Server-Sent Events (SSE). Clients that send `Accept: application/json` receive a collected JSON response from the same handler with no code changes.

Multi-tenancy is built in: add a TenantBackend and every skill gets per-user variants — same input/output schema, different handler implementation, isolated routing. Variants move through sandbox → preview → promoted status. Per-user sandboxes (local subprocess, Docker, Kubernetes) provide process isolation for untrusted code.

- PyPI: https://pypi.org/project/harnessapi/
- GitHub: https://github.com/edwinjosechittilappilly/harnessapi
- Docs: https://edwinjosechittilappilly.github.io/harnessapi/

## Docs

- [Introduction](https://edwinjosechittilappilly.github.io/harnessapi/introduction/): harnessapi — the skill-first Python framework for streaming APIs and MCP tools. Write a capability. Get an HTTP endpoint, an MCP tool, and Swagger docs — simultaneously.
- [Quick start](https://edwinjosechittilappilly.github.io/harnessapi/guides/quickstart/): Get a streaming HTTP API and MCP tool running in 60 seconds with harnessapi.
- [Installation](https://edwinjosechittilappilly.github.io/harnessapi/guides/installation/): Install harnessapi with uv, pip, or try it instantly with uvx. Covers requirements, optional extras, and contributor setup.
- [Skill folders](https://edwinjosechittilappilly.github.io/harnessapi/concepts/skill-folders/): The complete reference for harnessapi skill folders — the core unit that becomes an HTTP endpoint, MCP tool, and Swagger entry automatically.
- [Streaming (SSE)](https://edwinjosechittilappilly.github.io/harnessapi/concepts/streaming/): How harnessapi uses Server-Sent Events for streaming skill output — event format, JSON mode, Python and JavaScript clients, error handling, and timeouts.
- [MCP tools](https://edwinjosechittilappilly.github.io/harnessapi/concepts/mcp/): How harnessapi automatically registers every skill as a Model Context Protocol tool, and how to connect Claude Desktop, Claude Code, Cursor, and other clients.
- [Factorial — streaming skill](https://edwinjosechittilappilly.github.io/harnessapi/examples/factorial/): A real harnessapi example — computing factorial step-by-step with SSE streaming and MCP tool exposure.
- [Summarizer — LLM skill](https://edwinjosechittilappilly.github.io/harnessapi/examples/summarizer/): Convert an LLM summarization function into a streaming harnessapi skill and MCP tool.
- [Web scraper](https://edwinjosechittilappilly.github.io/harnessapi/examples/web-scraper/): Wrap a web scraping function as a harnessapi skill — streaming scraped content and exposing it as an MCP tool.
- [Image captioner](https://edwinjosechittilappilly.github.io/harnessapi/examples/image-captioner/): Expose a vision LLM as a harnessapi skill — stream image captions via SSE and call it as an MCP tool from Claude Desktop.
- [Agentic RAG — multi-tenancy](https://edwinjosechittilappilly.github.io/harnessapi/examples/agentic-rag/): A complete agentic RAG server with per-tenant vector isolation, streaming GPT-4o answers, MCP tools, and an admin MCP for per-tenant skill customization.
- [Multi-tenancy overview](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/): How harnessapi lets every user own a customized version of any skill — same schema, different implementation, isolated routing — with one line added to HarnessAPI.
- [Variant lifecycle](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/variants/): How to clone, customize, validate, test, and promote per-tenant skill variants in harnessapi.
- [Preview & staging](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/preview/): How to use preview status to route real tenant traffic through a variant before committing to a full promotion.
- [Per-user sandboxes](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/sandboxes/): How to provision isolated per-tenant sandbox processes for full code execution isolation in harnessapi.
- [Storage backends](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/storage/): How harnessapi persists skill variants and sandbox connections across server restarts, and how to choose or implement a storage backend.
- [Admin MCP server](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/admin-mcp/): How to expose the harnessapi tenant management API as MCP tools so agents can manage skill variants natively through Claude Desktop or Claude Code.
- [API reference](https://edwinjosechittilappilly.github.io/harnessapi/multi-tenancy/api-reference/): Complete endpoint list and TenantBackend configuration reference for harnessapi multi-tenancy.
- [Convert an agentskills.io skill](https://edwinjosechittilappilly.github.io/harnessapi/guides/convert-skill/): How to convert an existing agentskills.io skill folder into a full harnessapi HTTP API and MCP tool.
- [Connect to Claude Desktop](https://edwinjosechittilappilly.github.io/harnessapi/guides/claude-desktop/): How to connect your harnessapi skills to Claude Desktop and Cursor as MCP tools.
- [Deploy to production](https://edwinjosechittilappilly.github.io/harnessapi/guides/deploy/): How to deploy a harnessapi app to production — Railway, Fly.io, Docker, or any ASGI host.
- [harnessapi init](https://edwinjosechittilappilly.github.io/harnessapi/reference/init/): Reference for the harnessapi init CLI command — scaffold new projects, convert agentskills.io skills, and wrap Python functions.
- [harnessapi run](https://edwinjosechittilappilly.github.io/harnessapi/reference/run/): Reference for the harnessapi run CLI command — start the development server with auto-reload.

## Optional: full content

For a single-file dump of all documentation prose, see:
https://edwinjosechittilappilly.github.io/harnessapi/llms-full.txt
