Connect MCP and provider-hosted tools

Tool location is part of your security and portability contract:

• Local callable tool: your application executes a function through the portable SDK tool loop.
• SDK-managed MCP tool: your application owns the MCP client and transport; discovered MCP methods become callable SDK tools.
• Provider-hosted tool: the provider executes search, file retrieval, code, remote MCP, or another native capability.

Hosted tools are not portable merely because they are passed through the common tools option.

Availability and stability

Surface	TypeScript	Python
SDK-managed MCP	createMcpToolSet() is stable	MCP discovery and registry helpers are stable
Local + MCP composition	Shared tool set; createMcpToolRegistry() is Beta	Stable ToolRegistry
Provider-hosted tools	Provider-native and experimental	Provider-native and beta
Provider-managed approvals	Provider/capability dependent	Beta; currently integrated for OpenAI and Azure OpenAI remote MCP

Published adapters do not imply identical hosted-tool support. Select the exact provider, model, transport, and tool class using the current provider guide.

SDK-managed MCP in TypeScript

createMcpToolSet() accepts an application-provided client with listTools() and callTool() methods:

import { Agent, createMcpToolSet } from "@zhivex-ai/sdk";
import type { McpClient } from "@zhivex-ai/sdk";

declare const myMcpClient: McpClient;

const mcpTools = await createMcpToolSet(myMcpClient, {
  includeTools: ["search_docs", "read_page"],
  trustServerToolAnnotations: false,
  maxListPages: 10,
  maxListedTools: 100,
  listToolsTimeoutMs: 5_000,
  callToolTimeoutMs: 20_000
});

const agent = new Agent({
  model,
  instructions: "Use documentation tools only when they improve the answer.",
  tools: mcpTools,
  maxSteps: 4
});

Opaque pagination, input schemas, declared structured outputs, cancellation, timeouts, and idempotency keys are handled by the wrapper. Server annotations are untrusted by default, so discovered calls require approval unless your application explicitly trusts the server annotations. Destructive or open-world hints still require approval.

SDK-managed MCP in Python

Python can own a stdio or HTTP MCP lifecycle through a stable registry:

import os

from zhivex_ai import (
    Agent,
    ApprovalDecision,
    create_mcp_tool_registry,
    create_openai,
    mcp_http_server,
    run_agent,
)


async def review_mcp_call(request):
    remote_name = request.tool_metadata.get("mcp_tool_name")
    if request.tool_source == "mcp" and remote_name == "search_docs":
        return ApprovalDecision(approved=True)
    return ApprovalDecision(approved=False, reason="MCP tool is not allowed.")

server = mcp_http_server(
    name="docs",
    url="https://mcp.example.com/api",
    headers={"authorization": f"Bearer {os.environ['MCP_SERVER_TOKEN']}"},
    timeout_ms=20_000,
)

async with await create_mcp_tool_registry(server) as tools:
    agent = Agent(
        name="docs_assistant",
        model=create_openai()("gpt-6-astra"),
        tools=tools,
        approval_policy=review_mcp_call,
    )
    result = await run_agent(agent=agent, prompt="Find the retention policy.")

All discovered Python MCP tools require approval by default, even when a server advertises readOnlyHint=true. After authenticating and reviewing a server, trusted_tools={"exact_remote_name"} can bypass approval for only those exact names. Keep lifecycle cleanup, authentication, and that allowlist in server-owned configuration.

Provider-hosted tools are native

Use hosted tools only when provider execution is the product requirement. Isolate them behind an application adapter because the tool names, approval events, stored files, response references, and retention behavior are provider-specific.

TypeScript example:

import { generateText } from "@zhivex-ai/sdk";
import { createOpenAI, openAIWebSearchTool } from "@zhivex-ai/openai";

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const result = await generateText({
  model: openai("gpt-6-astra"),
  prompt: "Verify the current release notes.",
  tools: { search: openAIWebSearchTool() }
});

Python makes the native boundary explicit:

from zhivex_ai import create_openai, generate_text, openai_web_search_tool

openai = create_openai()
result = await generate_text(
    model=openai.native.language_model("gpt-6-astra"),
    prompt="Verify the current release notes.",
    tools={"search": openai_web_search_tool(search_context_size="high")},
)

Portable/foundation Python models reject hosted tools rather than silently treating them as local callables.

Trust and authorization checklist

• Authenticate and pin each MCP server; constrain commands, URLs, roots, environment variables, headers, pages, tool counts, payload sizes, and deadlines.
• Treat descriptions, schemas, annotations, and tool output as untrusted data. Validate results before using them in SQL, shell commands, filesystem paths, browser actions, or prompts.
• Approval is not authorization. Bind the approver, tenant, tool version, exact arguments, expiration, and one-time decision in application state.
• Forward cancellation and idempotency into external tools. If a timed-out side effect has an unknown outcome, reconcile it before retrying.
• Do not expose provider or MCP credentials to browser code. Redact credentials and sensitive tool inputs/outputs from traces.
• Provider-hosted storage and code environments have their own region, network, retention, and billing semantics. Review those semantics for the exact provider feature.

For model-directed delegation, see subagents. For the surrounding control boundary, see production architecture.

Experimental MCP server in TypeScript 1.34

@zhivex-ai/sdk/mcp-server and @zhivex-ai/core/mcp-server are experimental servers that expose local tools and agents to Claude Code, Cursor, and other MCP clients. The protocol pin is 2025-11-25. Bind process stdio with serveMcpStdio from @zhivex-ai/sdk/mcp-server-stdio. Browser bundles of the stdio binder throw McpServerError. Do not import the server from the SDK root.

Tools and agent registrations that require approval are not executed. An in-run approval pause is returned as APPROVAL_REQUIRED and is not resumed. Every runtime export is classified by MCP_SERVER_API_STABILITY_MANIFEST. The Stable HTTP client below is the opposite direction: your application calls another MCP server.

See the 1.34 MCP server guide.

MCP HTTP and hosted search in TypeScript 1.29

MCP now includes optional resources, resource templates and prompts alongside tools. Since 1.29.0, the opt-in @zhivex-ai/sdk/mcp-http and @zhivex-ai/core/mcp-http entrypoints are Stable for the documented MCP 2025-11-25 subset. They provide bounded Streamable HTTP and public-client OAuth PKCE discovery. MCP_HTTP_API_STABILITY_MANIFEST classifies this focused entrypoint; createMcpToolRegistry() remains Beta. Credentials remain host-owned. Handle typed authentication failures and indeterminate execution without blindly retrying tool side effects.

Qwen Responses preserves public URL citations through streaming and terminal snapshots. Gemini GenerateContent retains bounded, deduplicated Google Search grounding, citation indices and attribution; Interactions has a separate contract. Typed hosted-tool metering and per-route limit evidence do not add prices or credit accounting. Unverified max_tool_calls limits are rejected.

close() cancels local work without deleting the remote session. This subset does not implement background GET streams, resumable SSE or automatic request replay. See the pinned MCP HTTP guide.