Connect to OpenAPI at runtime

Use MCPClient.from_openapi(...) to connect directly to an API described by OpenAPI. Harnest loads the spec and constructs a local FastMCP bridge when the MCP connection opens. There is no client-generation command or provisioning step.

Declare a client

Place the specification at mcp/_specs/crm.yaml and declare its connection:

mcp/crm.py

from pathlib import Path

from harnest.mcp import MCPClient

def client() -> MCPClient:
    """Connect to CRM through its OpenAPI specification."""
    return MCPClient.from_openapi(
        Path(__file__).parent / "_specs" / "crm.yaml",
        headers={"Authorization": "Bearer ${CRM_API_TOKEN}"},
    )

The _specs directory is excluded from Python capability discovery and copied into the compiled agent. Resolving the path beside __file__ keeps it valid after deployment. A relative string path resolves against the runtime working directory. Each from_openapi call creates one standard MCP client for one spec. Declare separate clients for separate APIs. To combine multiple specs into one remotely hosted MCP server, use harnest_fused.

Runtime dependency

Add the optional extra to the agent’s existing dependency list:

pyproject.toml

[project]
# Keep your existing project name, version, and dependencies.
dependencies = ["harnest[openapi]"]

Run harnest env sync . to update the managed environment and its lock. If you manage your own interpreter, install harnest[openapi] alongside your framework’s MCP adapter.

Load a URL

MCPClient.from_openapi(
    "https://crm.example.com/openapi.json",
    base_url="https://api.example.com/v1",
    headers={"X-API-Key": "${CRM_API_KEY}"},
    tools=["get_customer", "list_orders"],
    prefix="crm",
)

base_url overrides the first top-level OpenAPI server URL. Supply it when a local spec has a relative server, lacks a server, or uses server variables. A relative server in a remote spec resolves against that spec’s URL. Remote specs are fetched at startup and reconnection, so their tools can change. Bundle a local spec for fixed deployments. Downloads do not follow redirects or receive API headers; download protected specs separately.

Credentials and policies

headers supports the same ${VARIABLE} references as other MCP connections. Values resolve when the connection opens and are sent only to the API. The spec’s securitySchemes do not automatically provision credentials or perform OAuth consent. The standard stdio client options apply, including tools, prefix, permission, tool_permissions, and timeout_seconds. Omit tools to expose all operations. See MCP Client for runtime permissions and trusted-code access.

Inspect and compile

harnest mcp inspect crm
harnest compile . --output .harnest/compiled

Inspection starts the connection; compilation does not load the spec or contact services. The connection owns a FastMCP stdio subprocess using Harnest’s Python environment. Outside an agent, use async with client.connect() for discovery and reads. Inside an invocation, call tools through context.mcp("crm").call_tool(...) or a native framework adapter.

Supported specifications

The bridge supports OpenAPI 3.0 and 3.1 in JSON or YAML through FastMCP 2.x. Bundle external $ref files or URLs into one document first; internal #/... references are retained. Input documents are limited to 16 MiB. Source and operation validation happens when the connection starts. Swagger 2.0, OpenAPI 3.2, and automatic OAuth flows are not supported by this bridge. The separate harnest_fused package can use fused-cli for explicit setup and Fused-managed execution.

Overview

Get started

Harnest Studio

Guides

API reference

Connect to OpenAPI at runtime

Declare a client

Runtime dependency

Load a URL

Credentials and policies

Inspect and compile

Supported specifications

​Declare a client

​Runtime dependency

​Load a URL

​Credentials and policies

​Inspect and compile

​Supported specifications

Declare a client

Runtime dependency

Load a URL

Credentials and policies

Inspect and compile

Supported specifications