GitHub

McpClientService

API reference for McpClientService.

A connected client (Effect's McpClient).

Attributes

AttributeTypeDescription
protocol_versionClientProtocolVersion
server_infoImplementation | None
instructionsstr | None
capabilitiesServerCapabilities

Functions

__init__

__init__(protocol_version, server_info, instructions, capabilities, _request, _deadline, _is_callable, _timeout, _skills) -> None
ParameterTypeDescription
protocol_versionClientProtocolVersion
server_infoImplementation | None
instructionsstr | None
capabilitiesServerCapabilities
_requestCallable[[str, JsonObject, McpTool | None], Effect[Any, McpClientError]]
_deadlineCallable[[Effect[Any, McpClientError], str, Duration | None], Effect[Any, McpClientError]]
_is_callableCallable[[McpTool], bool]
_timeoutDuration
_skillsSkillsClient

list_tools

list_tools(*, timeout=None, limits=None) -> Effect[list[McpTool], McpClientError]

Every tool the server lists (and this transport can call), within the client's discovery deadline and limits (timeout and limits override them).

ParameterTypeDescription
timeoutDurationInput | None = None
limitsDiscoveryLimitsOptions | None = None

Returns Effect[list[McpTool], McpClientError]

def list_tools(
    self, *, timeout: DurationInput | None = None, limits: DiscoveryLimitsOptions | None = None
) -> Effect[list[McpTool], McpClientError]:
    """Every tool the server lists (and this transport can call), within
    the client's discovery deadline and limits (``timeout`` and
    ``limits`` override them)."""
    return self._list("tools", LIST_TOOLS.success_schema, timeout, limits).map(
        lambda tools: [t for t in tools if self._is_callable(t)]
    )

list_prompts

list_prompts(*, timeout=None, limits=None) -> Effect[list[Prompt], McpClientError]

Every prompt the server lists, with the bounds of list_tools; none when it does not advertise prompts. Fails with an McpClientError: a ConfigurationError for invalid limits, a limit or timeout error past the bounds, or the request's error.

ParameterTypeDescription
timeoutDurationInput | None = None
limitsDiscoveryLimitsOptions | None = None

Returns Effect[list[Prompt], McpClientError]

def list_prompts(
    self, *, timeout: DurationInput | None = None, limits: DiscoveryLimitsOptions | None = None
) -> Effect[list[Prompt], McpClientError]:
    """Every prompt the server lists, with the bounds of ``list_tools``;
    none when it does not advertise prompts. Fails with an
    ``McpClientError``: a ``ConfigurationError`` for invalid limits, a
    limit or timeout error past the bounds, or the request's error."""
    return self._list("prompts", LIST_PROMPTS.success_schema, timeout, limits)

list_resources

list_resources(*, timeout=None, limits=None) -> Effect[list[Resource], McpClientError]

Every resource the server lists, with the bounds and errors of list_prompts; none when it does not advertise resources.

ParameterTypeDescription
timeoutDurationInput | None = None
limitsDiscoveryLimitsOptions | None = None

Returns Effect[list[Resource], McpClientError]

def list_resources(
    self, *, timeout: DurationInput | None = None, limits: DiscoveryLimitsOptions | None = None
) -> Effect[list[Resource], McpClientError]:
    """Every resource the server lists, with the bounds and errors of
    ``list_prompts``; none when it does not advertise resources."""
    return self._list("resources", LIST_RESOURCES.success_schema, timeout, limits)

list_skills

list_skills(*, timeout=None, limits=None, on_invalid_skill=None) -> Effect[list[Skill], McpClientError]

Every skill the server lists, with the bounds of list_tools; none when it does not declare the Skills extension. An entry breaking the extension's rules fails the scan, unless on_invalid_skill is given: it is then told of each and the entry is left out. The skill methods require extensions={"skills": True}.

ParameterTypeDescription
timeoutDurationInput | None = None
limitsDiscoveryLimitsOptions | None = None
on_invalid_skillOnInvalidSkill | None = None

Returns Effect[list[Skill], McpClientError]

def list_skills(
    self,
    *,
    timeout: DurationInput | None = None,
    limits: DiscoveryLimitsOptions | None = None,
    on_invalid_skill: OnInvalidSkill | None = None,
) -> Effect[list[Skill], McpClientError]:
    """Every skill the server lists, with the bounds of ``list_tools``;
    none when it does not declare the Skills extension. An entry breaking
    the extension's rules fails the scan, unless ``on_invalid_skill`` is
    given: it is then told of each and the entry is left out. The skill
    methods require ``extensions={"skills": True}``."""
    return self._skills.list_skills(_optional_seconds(timeout), limits, on_invalid_skill)

get_skill

get_skill(uri, *, timeout=None) -> Effect[Skill, McpClientError]

The skill whose SKILL.md is at uri, listed or not. Unbounded unless given a timeout.

ParameterTypeDescription
uristr
timeoutDurationInput | None = None

Returns Effect[Skill, McpClientError]

def get_skill(
    self, uri: str, *, timeout: DurationInput | None = None
) -> Effect[Skill, McpClientError]:
    """The skill whose ``SKILL.md`` is at ``uri``, listed or not.
    Unbounded unless given a ``timeout``."""
    return self._skills.get_skill(uri, _optional_seconds(timeout))

read_resource_directory

read_resource_directory(uri, *, timeout=None, limits=None) -> Effect[list[Resource], McpClientError]

The direct children of a directory of a skill namespace, with the bounds of list_tools. Requires the server's directoryRead.

ParameterTypeDescription
uristr
timeoutDurationInput | None = None
limitsDiscoveryLimitsOptions | None = None

Returns Effect[list[Resource], McpClientError]

def read_resource_directory(
    self,
    uri: str,
    *,
    timeout: DurationInput | None = None,
    limits: DiscoveryLimitsOptions | None = None,
) -> Effect[list[Resource], McpClientError]:
    """The direct children of a directory of a skill namespace, with the
    bounds of ``list_tools``. Requires the server's ``directoryRead``."""
    return self._skills.read_resource_directory(uri, _optional_seconds(timeout), limits)

read_skill_resource

read_skill_resource(skill, uri, *, timeout=None) -> Effect[ReadResourceResult, McpClientError]

Read a file of skill, failing with a ValidationError unless its bytes match the SHA-256 digest and size of the manifest and, for SKILL.md, its frontmatter equals the listed one. A "dynamic" skill has no digests: any file in its directory is read, and its SKILL.md still checked. A file outside the manifest or directory is never requested. Unbounded unless given a timeout.

ParameterTypeDescription
skillSkill
uristr
timeoutDurationInput | None = None

Returns Effect[ReadResourceResult, McpClientError]

def read_skill_resource(
    self, skill: Skill, uri: str, *, timeout: DurationInput | None = None
) -> Effect[ReadResourceResult, McpClientError]:
    """Read a file of ``skill``, failing with a ``ValidationError`` unless
    its bytes match the SHA-256 digest and size of the manifest and, for
    ``SKILL.md``, its frontmatter equals the listed one. A ``"dynamic"``
    skill has no digests: any file in its directory is read, and its
    ``SKILL.md`` still checked. A file outside the manifest or directory
    is never requested. Unbounded unless given a ``timeout``."""
    return self._skills.read_skill_resource(skill, uri, _optional_seconds(timeout))

get_prompt

get_prompt(prompt, arguments=None, *, timeout=None) -> Effect[GetPromptResult, McpClientError]

The messages of prompt filled with arguments. Fails with an UnsupportedError when the server does not advertise prompts, a ValidationError for an invalid result, or the request's McpClientError. Unbounded unless given a timeout.

ParameterTypeDescription
promptPrompt
argumentsMapping[str, str] | None = None
timeoutDurationInput | None = None

Returns Effect[GetPromptResult, McpClientError]

def get_prompt(
    self,
    prompt: Prompt,
    arguments: Mapping[str, str] | None = None,
    *,
    timeout: DurationInput | None = None,
) -> Effect[GetPromptResult, McpClientError]:
    """The messages of ``prompt`` filled with ``arguments``. Fails with
    an ``UnsupportedError`` when the server does not advertise prompts,
    a ``ValidationError`` for an invalid result, or the request's
    ``McpClientError``. Unbounded unless given a ``timeout``."""
    params: JsonObject = {"name": prompt["name"]}
    if arguments is not None:
        params["arguments"] = dict(arguments)
    got = self._call("prompts", "prompts/get", params).flat_map(
        lambda raw: _decode(GET_PROMPT_RESULT, raw)
    )
    return self._deadline(got, "prompts/get", _optional_seconds(timeout))

read_resource

read_resource(uri, *, timeout=None) -> Effect[ReadResourceResult, McpClientError]

The contents of the resource at uri. Fails with an UnsupportedError when the server does not advertise resources, a ValidationError for an invalid result, or the request's McpClientError. Unbounded unless given a timeout.

ParameterTypeDescription
uristr
timeoutDurationInput | None = None

Returns Effect[ReadResourceResult, McpClientError]

def read_resource(
    self, uri: str, *, timeout: DurationInput | None = None
) -> Effect[ReadResourceResult, McpClientError]:
    """The contents of the resource at ``uri``. Fails with an
    ``UnsupportedError`` when the server does not advertise resources, a
    ``ValidationError`` for an invalid result, or the request's
    ``McpClientError``. Unbounded unless given a ``timeout``."""
    read = (
        self._call("resources", "resources/read", {"uri": uri})
        .tap(self._check_cacheable)
        .flat_map(lambda raw: _decode(READ_RESOURCE_RESULT, raw))
    )
    return self._deadline(read, "resources/read", _optional_seconds(timeout))

call_tool

call_tool(tool: McpTool, arguments: Mapping[str, Any] | None = None, *, timeout: DurationInput | None = None) -> Effect[CallToolResult, McpClientError]
call_tool[A, R](tool: McpTool, arguments: Mapping[str, Any] | None = None, *, schema: S.Codec[A, Any, R, Any], timeout: DurationInput | None = None) -> Effect[A, McpClientError, R]

Call tool. With schema, its structuredContent decoded (a tool error then fails with ToolError); else the whole result. Unbounded unless given a timeout.

ParameterTypeDescription
tool
arguments= None
schema= None
timeout= None
@overload
def call_tool(
    self,
    tool: McpTool,
    arguments: Mapping[str, Any] | None = None,
    *,
    timeout: DurationInput | None = None,
) -> Effect[CallToolResult, McpClientError]: ...
@overload
def call_tool[A, R](
    self,
    tool: McpTool,
    arguments: Mapping[str, Any] | None = None,
    *,
    schema: S.Codec[A, Any, R, Any],
    timeout: DurationInput | None = None,
) -> Effect[A, McpClientError, R]: ...
def call_tool(
    self,
    tool: McpTool,
    arguments: Mapping[str, Any] | None = None,
    *,
    schema: S.Codec[Any, Any, Any, Any] | None = None,
    timeout: DurationInput | None = None,
) -> Effect[Any, McpClientError, Any]:
    """Call ``tool``. With ``schema``, its ``structuredContent`` decoded
    (a tool error then fails with ``ToolError``); else the whole result.
    Unbounded unless given a ``timeout``."""
    params: JsonObject = {"name": tool["name"]}
    if arguments is not None:
        params["arguments"] = dict(arguments)

    def typed(result: CallToolResult) -> Effect[Any, McpClientError, Any]:
        if schema is None:
            return succeed(result)
        if result.get("isError") is True:
            return fail(failure(ToolError(result)))
        decode = cast(
            "Callable[[object], Effect[Any, S.SchemaError, Any]]",
            S.decode_unknown_effect(schema),
        )
        structured: object = result.get("structuredContent")
        return decode(structured).map_error(
            lambda cause: failure(
                ValidationError("MCP structured result validation failed", cause)
            )
        )

    called = (
        self._call("tools", "tools/call", params, tool)
        .flat_map(lambda raw: _decode(CALL_TOOL_RESULT, raw))
        .flat_map(typed)
    )
    return self._deadline(called, "tools/call", _optional_seconds(timeout))