MCP Client

MCPClient declares a connection to an external MCP server. Direct clients live under root mcp/; each public filename supplies the connection identity and exports a zero-argument client() factory returning MCPClient.

Scaffold a connection

Create an authenticated Streamable HTTP client without putting its token in source:

harnest add mcp catalog \
  --url https://mcp.example.com/mcp \
  --token-env CATALOG_MCP_TOKEN

The generated mcp/catalog.py reads the token through ${CATALOG_MCP_TOKEN}, sends it as Authorization: Bearer <token>, and prefixes discovered tool names with catalog_. Choose where and how the token is sent when a server uses a different header scheme:

harnest add mcp internal \
  --url https://mcp.example.com/mcp \
  --token-env INTERNAL_MCP_KEY \
  --token-header X-API-Key \
  --token-prefix=

Flag	Behavior
`--url`	Required HTTP or HTTPS MCP endpoint
`--transport`	`streamable-http` by default; use `sse` only for a legacy server
`--token-env`	Environment variable that supplies the token; omit for an unauthenticated server
`--token-header`	Destination header; defaults to `Authorization`
`--token-prefix`	Text before the token; defaults to `Bearer` ; use an empty value for a raw token
`--project`	Agent root; defaults to the current directory

The command accepts only the environment variable’s name. It rejects token values, credentials embedded in URLs, invalid header names, and advanced-mode projects where mcp/ discovery is not active.

Property	Rule
Location	`mcp/<name>.py`
Export	`client()`
Factory arguments	None
Preferred transport	Streamable HTTP
Legacy transport	SSE
Connection time	Runtime, not compile time
Credentials	Deployment environment or invocation credential provider
Runtime permissions	Optional client-wide `permission` and per-tool `tool_permissions`

mcp/catalog.py

import os

from harnest.mcp import MCPClient

def client():
    """Connect to the catalog MCP server."""

    return MCPClient.streamable_http(
        os.environ["CATALOG_MCP_URL"],
        headers={"Authorization": f"Bearer {os.environ['CATALOG_MCP_TOKEN']}"},
    )

Use MCPClient.sse(...) only for a legacy SSE server. Compilation does not connect. Tool discovery is lazy; explicitly configured subscriptions start with the serving runtime.

Discover what a server provides

Developers do not need to know resource URIs or prompt names in advance. From the agent folder, query a configured connection:

harnest mcp inspect catalog
harnest mcp inspect catalog --json
harnest mcp inspect catalog --catalog resources
harnest mcp read catalog 'catalog://handbook'
harnest mcp prompt catalog summarize --arg topic='Returns policy'

Use identifiers returned by discovery and add --project ./my-agent when outside the agent folder. Inspection uses the agent’s environment and credentials without starting models or subscriptions. Inspection returns capabilities, tool schemas, resources, URI templates, and prompt argument definitions. Each catalogue is one page: pass a returned nextCursor to harnest mcp inspect catalog --catalog resources --cursor '…'. The other catalogues are tools, resource-templates, and prompts. Servers without an optional capability return an empty catalogue. The local playground’s MCP view offers the same discovery and explicit retrieval. It accepts only loopback, same-origin requests and is absent from deployed artifacts without the development UI.

Give the agent access to context

The connection above is enough. Managed ADK and LangGraph agents receive namespaced helpers based on the server’s advertised capabilities and your allowlists:

Available capability	Helpers shown to the model
Tools only	Remote tools; no extra local helpers
Resources	List resources, list URI templates, read a resource
Prompts	List prompts, fetch a prompt with arguments

Resource and prompt helpers are additive. Setting resources=[] or prompts=[] hides that category’s helpers and denies retrieval. An empty catalogue does not disable an advertised capability: resources or prompts can appear later. Harnest does not eagerly inject their contents into instructions. Trusted code can use the same governed operations:

tools/load_context.py

from harnest import context
from harnest.agent import tool

@tool
async def load_context(uri: str):
    """Read a resource selected from the MCP catalogue."""

    return await context.mcp("catalog").read_resource(uri)

See the MCP discovery operation reference. Trusted operations enforce permissions and invocation lifetime even when hidden from the model. Unsupported catalogues are empty; unsupported reads fail. Prompt arguments are strings, and returned messages are reference data. Outside an invocation, use a developer-owned connection:

from harnest.mcp import MCPClient

connection = MCPClient.streamable_http("https://mcp.example.com/mcp")

async def inspect_catalog():
    """Discover identifiers and argument schemas without loading a model."""

    async with connection.connect() as client:
        return await client.inspect()

connect() uses the LangGraph lifecycle identity by default; pass framework="adk" when sharing an ADK-owned lifecycle. Resource/prompt requests are independently scoped; do not rely on per-session server state shared with tool calls. Streamable HTTP tries protocol 2026-07-28 discovery, falling back to SDK initialization for unsupported or older servers. Authentication, header-validation, and transport failures do not trigger fallback. Inspect the selected protocolVersion with harnest mcp inspect CLIENT --json. Tool calls are sent once; Harnest does not automatically replay them after a disconnect or an input-required response. Interactive multi-round-trip input handling is not supported on the newer HTTP path yet. Stdio and legacy SSE continue using the installed SDK’s supported protocol versions.

Restrict retrieval

return MCPClient.streamable_http(
    os.environ["CATALOG_MCP_URL"],
    permission="catalog.connect",
    resources=["catalog://handbook"],
    prompts=["summarize"],
    max_content_bytes=262144,
)

Omit resources or prompts to allow discovery and retrieval of that category; use [] to deny it. Allowlists match exact URIs or prompt names. Listing an allowed URI template does not authorize arbitrary expanded URIs: concrete reads must also be allowed. max_content_bytes bounds returned content (default 1 MiB, configurable from 1 KiB to 16 MiB), not the SDK’s transport allocation. Binary content stays in MCP’s encoded representation. Client-wide permission protects resource/prompt helpers as well as remote tools. tool_permissions applies only to named remote tools. No permission tag means no access when a default-deny Agent Runtime Principal is active. Subscriptions belong on the MCP client, not on a public HTTP route. Import an async handler from the agent’s lib/:

mcp/catalog.py

import os

from harnest.mcp import MCPClient, MCPSubscription
from harnest.lib.catalog_events import handle_update

def client():
    """Subscribe to the server's retained latest-event resource."""

    return MCPClient.streamable_http(
        os.environ["CATALOG_MCP_URL"],
        headers={"Authorization": f"Bearer {os.environ['CATALOG_MCP_TOKEN']}"},
        subscriptions=[MCPSubscription(
            uri="catalog://events/latest",
            handler=handle_update,
            read_on_start=True,
            read_on_reconnect=True,
        )],
    )

lib/catalog_events.py

from harnest.logging import get_logger
from harnest.mcp import MCPResourceEvent

async def handle_update(event: MCPResourceEvent) -> None:
    """Validate the retained value before handing it to application services."""

    contents = event.resource["contents"]
    get_logger("catalog").info(
        "catalog.resource.received", reason=event.reason, blocks=len(contents)
    )
    # Parse and validate contents, then call your application service here.
    # Use the provider's event ID as an idempotency key for durable side effects.

event.reason is start, update, or reconnect. Handlers have no inherited user/session context: choose an application-authorized identity explicitly if your service invokes an agent or enqueues a task. The handler timeout defaults to 30 seconds (handler_timeout_seconds). No public subscription-management endpoint is created. Subscriptions default to SDK 1.x resources/subscribe. For stateless Streamable HTTP endpoints, explicitly set MCPSubscription(method="subscriptions/listen", ...) to use protocol 2026-07-28. Harnest subscribes before its initial read and rereads after reconnecting. Initial failure stops startup; established listeners retry with backoff up to 30 seconds. Shutdown cancels listeners before closing clients.

Latest-value recovery is not replay of every missed event. Identical content is deduplicated in process only, after successful handling. Restarts and multiple replicas can deliver again. Make handlers idempotent; use a durable queue or provider event history when every event must be processed.

Framework adapters

Framework	Adapter behavior
ADK	Uses the native MCP toolset
LangGraph	Uses its MCP adapter and discovers remote tools at runtime

Harnest keeps connection identity and approval policy consistent. Same-named tools on different servers remain distinct.

Limit tools by runtime principal

Use permission= to require one grant for every tool from a client. Use tool_permissions= to add a requirement to selected remote tools:

return MCPClient.streamable_http(
    os.environ["CATALOG_MCP_URL"],
    permission="catalog.connect",
    tool_permissions={
        "search_products": "catalog.search",
        "update_product": "catalog.write",
    },
)

An active Agent Runtime Principal must hold every permission required by the client and operation. Untagged operations are unavailable. Harnest checks exposure and execution; the remote server must still authorize requests.

Call MCP from trusted code

Use the invocation-scoped facade when a tool or service chooses the remote operation:

tools/search_catalog.py

from harnest import context
from harnest.agent import tool

@tool
async def search_catalog(query: str):
    """Search the catalog through the configured MCP client."""

    return await context.mcp("catalog").call_tool(
        "search_products",
        {"query": query},
    )

The facade exposes neither the raw transport nor credentials. Calls use the same approval, Tool Lifecycle, and MCP Client Lifecycle paths as model-selected MCP tools.

Authentication and gateways

Read URLs and static credentials from the deployment environment. For user-scoped access, resolve a token through Authentication and Credentials. Customize the HTTP client only for a gateway, mTLS, or transport policy. Put shared clients in lifecycle resources because adapters may call the factory more than once.

Direct connections and plugins

Need	Use
Connection for one agent	Root `mcp/`
Portable MCP declarations, optionally with Agent Skills	Agent Plugin using `mcp.json`
MCP plus SDK, context, or lifecycle behavior	Harnest Extension

Combine APIs with Fused

Use harnest_fused to provision one MCP server from selected operations across multiple OpenAPI specifications.

Connect to OpenAPI at runtime

Use MCPClient.from_openapi(...) to load a specification at connection startup with normal MCP policies and credential references.

API reference

Reference: harnest.agent, harnest.logging.

Overview

Get started

Harnest Studio

Guides

API reference

Scaffold a connection

Discover what a server provides

Give the agent access to context

Restrict retrieval

Framework adapters

Limit tools by runtime principal

Call MCP from trusted code

Authentication and gateways

Direct connections and plugins

Combine APIs with Fused

Connect to OpenAPI at runtime

API reference

​Scaffold a connection

​Discover what a server provides

​Give the agent access to context

​Restrict retrieval

​Subscribe to retained resource updates

​Framework adapters

​Limit tools by runtime principal

​Call MCP from trusted code

​Authentication and gateways

​Direct connections and plugins

​Combine APIs with Fused

​Connect to OpenAPI at runtime

​API reference

Scaffold a connection

Discover what a server provides

Give the agent access to context

Restrict retrieval

Subscribe to retained resource updates

Framework adapters

Limit tools by runtime principal

Call MCP from trusted code

Authentication and gateways

Direct connections and plugins

Combine APIs with Fused

Connect to OpenAPI at runtime

API reference