MCP Server Interaction

The StackOne AI SDK interacts with Model Context Protocol (MCP) servers to fetch tool catalogs and execute actions. The SDK uses MCP as the primary route to discover tools at runtime, ensuring the schema shown to an AI model matches the server-side configuration exactly. This interaction allows the SDK to manage large catalogs that would otherwise exceed model context limits through semantic search and meta-tool execution.

Sources: CLAUDE.md:15-20, README.md:15-25

MCP Communication Flow

The SDK acts as an MCP client that communicates with the StackOne MCP endpoint. The process involves initializing a session, listing available tools with pagination support, and calling specific tools. The SDK pins the parameter style to flat_prefixed on the /mcp listing URL to ensure the schema matches the RPC execution requirements.

The diagram shows the lifecycle of an MCP connection, from transport establishment to tool execution.
Sources: stackone_ai/tools.py:102-145, tests/test_fetch_tools.py:440-455

Tool Discovery and Fetching

The fetch_mcp_tools function manages the retrieval of the tool catalog. It utilizes a ClientSession from the mcp library and handles the underlying streamable-HTTP transport.

Key Fetching Mechanisms

• Authentication: The SDK builds a Basic Auth header using the provided API key.
• Account Scoping: Requests include the x-account-id header to scope the tool discovery. If no account is provided, the SDK performs account discovery via the /accounts endpoint.
• Timeouts: The SDK applies the user-defined timeout to every leg of the MCP transport, including the SSE (Server-Sent Events) read timeout.
• Error Handling: The _describe_mcp_failure function unwraps complex ExceptionGroup errors from the MCP client's TaskGroup into actionable StackOneAPIError or ToolsetLoadError instances.

Sources: stackone_ai/tools.py:92-100, stackone_ai/tools.py:176-210, tests/test_fetch_tools.py:495-515

Tool Modes

The SDK supports two distinct modes for interacting with the MCP server, defined by the ToolMode literal.

Sources: stackone_ai/types.py:19-27, CLAUDE.md:30-40, tests/test_fetch_tools.py:537-550

Meta-Tool Execution Logic

In search_execute mode, the SDK leverages specialized MCP tools to handle high-volume catalogs. The *_search_actions tool allows natural language searching for actions, while *_execute_action runs the selected action by ID.

This flowchart illustrates the flow of natural language search to final payload retrieval using MCP meta-tools.
Sources: stackone_ai/tools.py:276-285, tests/test_fetch_tools.py:575-595

Result Parsing and Error Propagation

MCP tool results arrive as CallToolResult objects. The SDK parses these into standard Python dictionaries while monitoring for the isError flag.

Parsing Logic

1. Content Extraction: The SDK concatenates text parts from the MCP result.
2. JSON Decoding: The payload is parsed as JSON. If decoding fails, the raw string is returned.
3. Error Identification: If isError is true, the SDK raises a StackOneAPIError. It attempts to extract a status code from the payload (checking keys like statusCode or status_code) to provide a branchable error for the caller.
4. Resource Handling: Any non-text content parts (e.g., images) are preserved in a content_parts key.

Sources: stackone_ai/tools.py:240-274, tests/test_fetch_tools.py:560-573

Summary

MCP Server interaction provides the backbone for the StackOne AI SDK's dynamic tool discovery. By utilizing the flat_prefixed parameter style and specialized meta-tools, the SDK maintains a compact, model-friendly catalog while providing access to extensive SaaS action sets. The integration ensures that errors and schemas are propagated faithfully from the server to the AI model.

Sources: CLAUDE.md:20-25, stackone_ai/tools.py:35-40