Agent plugins

A plugin contains	A plugin does not contain
One or more MCP clients	Another agent
One or more Agent Skills	Lifecycle callbacks
Optional skill references, assets, and scripts	Embedded credentials

A plugin contains

A plugin does not contain

One or more MCP clients

Another agent

One or more Agent Skills

Lifecycle callbacks

Optional skill references, assets, and scripts

Embedded credentials

plugins/ └── warehouse/ ├── mcp/ │ └── bigquery.py └── skills/ └── query-warehouse/ ├── SKILL.md └── references/ # optional

Plugin properties

Property	Rule
Plugin name	Comes from the directory name
MCP identity	Comes from the client filename
MCP factory	Must be `client()` with no parameters
Skill name	Must match the skill directory
Completeness	A non-empty plugin needs at least one MCP client and one skill
Discovery	Deterministic by plugin name
Credentials	Resolve from deployment settings or a credential provider

The MCP client follows the same rules as a direct client:

import os

from harnest.mcp import MCPClient


def client():
    return MCPClient.streamable_http(
        os.environ["BIGQUERY_MCP_URL"],
        prefix="bigquery",
    )

The skill should tell the agent which MCP tools to choose, what inputs they need, how to read the result, and what to do when the connection fails.

Plugin clients join direct clients from mcp/. Plugin skills join direct skills from skills/. Duplicate skill names or identical connection configurations fail compilation instead of shadowing one another.

For selective approval, name the server’s original tool before any prefix. Harnest rejects unknown names after remote discovery.

Connect directly to MCP

Use a direct connection when it belongs to one agent.

Add lifecycle behavior

Use an extension for persistence, guardrails, auditing, or native middleware.

Overview

Get started

Build agents

Runtime

Reference

Agent plugins

Plugin properties

Connect directly to MCP

Add lifecycle behavior

​Plugin properties

Connect directly to MCP

Add lifecycle behavior

Plugin properties